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PREFACE 


The PDP-11 COBOL User's Guide is intended primarily for reference use. 
It is a companion guide to the PDP-11 COBOL Language Reference Manual. 
Because it is not a tutorial guide for beginning programmers, you 
should have a working knowledge of the COBOL language. 


This guide describes the COBOL file structures, data formats; some of 
the features of the PDP-11 COBOL Version 4 compiler, error messages 
generated by the compiler and run-time systems, I/O devices available 
with the system, some hints on good programming practices, some 
techniques for debugging source programs, and a description of the 
PDP-11 COBOL utility programs, Merge and REFORMAT. 


xV 


ACKNOWLEDGMENTS 


COBOL is an industry language and is not the property of any company 
or group of companies, or of any organization or group of 
Organizations. 


No warranty, expressed or implied, is made by any contributor or by 
the CODASYL COBOL Committee as to the accuracy and functioning of the 
programming system and language. Moreover, no responsibility is 
assumed by any contributor, or by the committee, in connection 
therewith. 


The authors and copyright holders of the copyrighted material used 
herein are: FLOW-MATIC (trademark of Sperry Rand Corporation), 
Programming for the UNIVAC (R) I and II, Data Automation Systems 
copyrighted 1958, 1959, by Sperry Rand Corporation; IBM Commercial 
Translator Form No. F28-8913, copyrighted 1959 by IBM; FACT, DSI 
27A5269-2769, copyrighted 1969 by Minneapolis-Honeywell. 


They have specifically authorized the use of this material, in whole 
or in part, in the COBOL specifications. Such authorization extends 
to the reproduction and use of COBOL specifications in programming 
Manuals or similar publications. 


Procedures have been established for the maintenance of COBOL. 
Inquiries concerning the procedures for proposing changes should be 


directed to the Chairman of the CODASYL COBOL Committee, P.O. Box 
190A Manroaawilla Da, 15146. 


ade EP bAVsse Ve eae 7 ay 


XV1 


CHAPTER 1 


INTRODUCTION 


The PDP-11 COBOL compiler translates ANS-74 COBOL source programs into 
relocatable object modules; it runs under the supervision of the 
following PDP-1l operating systems: 

® RSTS/E 

8 RSX-11M 

e IAS 


To run a COBOL program, you follow a five-step process: 
e Prepare a source program 
6 Compile a source program 
e Merge or prepare an overlay description file (optional) 
e Task-build object modules into an executable task 
e Execute the task 


The PDP-11 COBOL compiler accepts COBOL source statements from source 
input files. This means that you must manually enter your source 
statements onto an acceptable medium prior to the compilation process. 


Once you have decided upon an input medium and format for your source 
input files and have created them, you compile the source program. 


The PDP-11 COBOL compiler reads source statements from the _ source 
input file, translates them into object code modules consisting of 
program sections (PSECTs), and produces the following files: 


e Listing (LST) 
e Object (OBJ) 
® Overlay Description Language (ODL) 


The listing file (LST) contains a listing of the source statements in 
the order in which they were compiled, any diagnostic error messages, 
and any optional special format listings, e.g., cross-reference 
listings and data and procedure maps. You obtain special format 
listings by appending an appropriate switch to the COBOL command line 
at compile-time. 


INTRODUCTION 


The object file (OBJ) contains a collection of program sections called 
PSECTS which are not executable. They must be linked into an 
executable task image by an operating system task called Task Builder. 
The ability to compile COBOL subprograms to produce linkable object 
files independently enables you to create modular programs. 


The Overlay Description Language (ODL) file contains directives that 
describe the overlay structure of the object module generated from the 
COBOL source program. ODL directives are generated into the ODL file 
for each overlayable object module program section. 


The compiler can compile only one source program or subprogram per 
command string execution. Therefore, a program which consists of a 
main program plus one or more subprograms requires multiple executions 
of the compiler. Each compilation generates a separate listing, ODL, 
and object file. The ODL files, in this instance, must be merged 
together into a single ODL file to be submitted as input to the Task 
Builder. 


To accomplish this, you use the Merge Utility, which performs’ the 
following functions: 


1. Merges the ODL statements from one or more ODL files into a 
Single ODL file 


2. Analyzes the I/O requirements for the entire task and 
provides directives to include the required I/O routines 


3. Inserts the missing but required ODL directives not provided 
by the compiler 


Whether you have a large segmented program, a main program plus 
Subroutines, or a small stand-alone program, the ODL files generated 
by the compiler require merging or modification. 


Task Builder provides you with a facility for linking separately 
compiled object modules into an executable task image. You can, 
depending on your knowledge of your operating system and PDP-11 COBOL, 
link object modules created by another programming language into your 
COBOL task image. Task Builder also allows you to take full advantage 
of the COBOL system library to selectively link into your COBOL task 
only those runtime support routines actually needed to run your task. 


The Task Builder, using the ODL file as a guide, provides the facility 
to build large amounts of code into a task by careful use of code 
segments that overlay each other. Careful use of segmentation or 
calls to subprograms within your COBOL source program will allow you 
to compile and execute large and complex COBOL programs. If you add 
some functionality to an existing COBOL program and find that, after 
task-building, the resulting task will not fit in memory, you have an 
alternative other than reprogramming: you can segment the program or 
make Subprograms out of some of the existing procedures, replacing 
these procedures with CALL statements to the newly created 
subprograms. When the source program has been compiled, the ODL fiie 
merged, and task-building accomplished, the task is ready to be 
executed. 
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INTRODUCTION 


The task is an executable form of the declarations and instructions 
represented in your COBOL source programs. It includes input-output 
routines and other subprograms that were inserted by the Task Builder 
as a result of your commands or the contents of the ODL file. It also 
includes the COBOL run-time system, which is a library of predefined 
routines that perform standard functions for your program, such as 
arithmetic and data movement. The run-time system is also referred to 
as the Object-Time System, or OTS. 


Figure 1-1 shows the process of preparing a COBOL program for 
execution. 


COBOL System Utility Programs 


The PDP-11l COBOL System includes two utility programs: 
MERGE 


The Merge Utility merges compiler-generated ODL files into a 
Singie ODL file. It also allows you to specify several options 
in it dialogue. Chapter 2 discusses Merge in detail. 


REFORMAT 


PDP-11 COBOL accepts source programs that were coded using either 
the ANSI 8f-column card reference format or the_ shorter, 
terminal-oriented PDP-1ll reference format. The REFORMAT utility 
program readS source programs that were coded in the PDP-1l 
terminal format and converts them to 68f-column ANSIi-compatible 
source programs. Chapter 8 describes the use of REFORMAT. The 
two reference formats are discussed in the PDP-1l COBOL Language 
Reference Manual. 
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Figure 1-1 Building A COBOL Task Image 


CHAPTER 2 


USING THE PDP-11 COBOL SYSTEM 


This chapter discusses the procedures for creating, compiling and 
using COBOL programs. The procedure can be described as a 5-step 
process: 


1. Creating or entering source programs. 


2. Compiling the source programs to produce object files and 
Overlay Descriptor Language (ODL) files. 
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files to produce an ODI file that 
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al specification for an executable task. 
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4. Task-building the object modules to produce the executable 
task. 


5. Executing the task and setting optional program switches. 


21. CREATING A SOURCE PROGRAM 


This section discusses the selection of a source reference format and 
the preparation of a source program file for input to the compiler. 


2.1.1 Choosing a Reference Format 


The PDP-11 COBOL compiler can accept source programs in either 
conventional or terminal reference format (both are described in the 
PDP-11 COBOL Reference Manual). However, it is important to note that 
you cannot mix reference formats in the same source program (including 
text copied from a COBOL library). 


Terminal format was designed to be easily used by programmers at 
interactive terminals; therefore, the compiler accepts terminal 
reference format as a default (you can use a compiler switch to 
specify conventional format). Using terminal format can result ina 
significant saving of file space used to store COBOL source programs. 
In addition, you will find that it is usually easier to edit source 
programs written in terminal format, because spacing requirements are 
more flexible. 
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You may want to select the conventional reference format if your COBOL 
program was Originally written that way for another compiler. 


You can convert a terminal format program to conventional format by 
using the REFORMAT utility, which is described in Chapter 8. Use 
REFORMAT to transport a terminal format program to a system that 
accepts only conventional format. You can also use it to match the 
formats of source files and COBOL library files if they are not the 
same. 


Digks-2 Entering a Source Program 


Create a source program file from your terminal by using a text 
editing program that is available on your system; or use a system 
utility to transfer existing source files from external media. You 
can also use a text editor to update existing source program files. — 


2.2 USING THE LIBRARY FACILITY (COPY) 

The PDP-11 COBOL library facility allows you to copy COBOL source 
language text from a library file into your COBOL program during 
compilation. One COPY statement can include large amounts of library 
source text in a program, eliminating a great deal of repetitious 
coding and the errors that often go along with it. The compiler 
treats the copied text as if it were a part of the source program; 
however, the copied material does not change the source program file 
in any way. 


The COBOL library facility provides two important benefits: 


1. Standardization of File and Coding Conventions 


A data file is usually processed by more than one program. 
Each of those programs must describe the characteristics of 
the file, such as file-name, blocking factor and _ record 
descriptions. The programs are often written by one 
programmer, then maintained and updated by another. Because 
it’ is often difficult for a programmer’ to understand a 
program written by someone else, many organizations design 
and code standardized file descriptions, then keep them in 
COBOL libraries; programmers then COPY the file descriptions 
into their programs, frequently without having to understand 
(or even know) their details. 


This technique also applies to Procedure Division code that 
is used in many different programs. For example, a library 
could contain a standardized routine to convert calendar 
dates to Julian dates, or to format standard report headings. 


2. Saving Time and Reducing Errors 


Defining and coding file and record descriptions are both 
time-consuming and error-prone activities. When the 
descriptions already exist in COBOL libraries, you can easily 
COPY them into a source program; you save time because you 
don't have to code them again, and you avoid potential errors 
in re-entering complex code. 
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Changing the format of a file is another common 
time-consuming chore. When a file format changes, you 
usually must change and recompile all programs that use _ the 
file. If the file description is in a COBOL library, only 
the library must be changed; individual programs often then 
need only recompilation, since the library coding changes are 
included by the COPY. 


Putting commonly used Procedure Division code in libraries 
yields the same benefits. 


2.2.1 Creating a COBOL Library File 


Each line of a COBOL library file must form syntactically correct 
COBOL text when it is merged into the source program. It can meet 
this condition by being itself syntactically correct or by becoming 
correct when it is merged with the source program. 


Library text must conform to the rules for the COBOL source reference 
format; for example, library text that will appear in Area A of the 
source program must be in Area A in the library file. You can write 
library text using either the conventional format or terminal format; 


however, the library text format must be the same as the source 
program into which it is merged. 


2.2.2 The COPY Statement 


va 


Y is a compiler-directing statement that merges a COBOL library 

e into a COBOL source program. The simplest form of the statement 
COPY text-name. 

Text-name must be either an alphanumeric literal or a file name. 

Remember that the COPY statement must end with a terminator period 

regardless of where it appears in the source program. 

If you specify a literal, the compiler uses its value as a file 

specification; therefore, you can include or omit all components of 

the file specification that are allowed by your operating system, such 

as device, UIC (or PPN), file type, and version number. The only 

required component is the file name itself. 

For example: 

COPY "DK1:[7,2MJACCFIL.XYZ;3". 


causes the compiler to access version number 3 of the file ACCFIL.XYZ 
in UIC [7,29] on the device DKl: 


If you use a file name in the COPY statement, the compiler uses  .LIB 
as the default file type. 


For example: 
COPY ACCOUNT. 
causes the compiler to access the latest version of the file 


ACCOUNT.LIB on the default device and UIC. 


273 
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Only four conditions require the use of the alphanumeric literal to 
indicate the full file specification for the copy statement: 


1. When the file type is other than .LIB. 
2. When the library file is not on the default device. 
3. When the library file is not in the default directory. 


‘4. When the default directory contains more than one version of 


: ; : 
the library file and you want to copy a version other than 


the latest. This condition cannot occur under RSTS/E, which 
does not support multiple file versions. 


Figure 2-1 demonstrates the use of the COPY statement to include 
Procedure Division code. Note that the format of the library text is 
maintained when it is included in the source program. 


COBOL Source Program Resulting Source Program 





PROCEDURE DIVISION. PROCEDURE DIVISION. 
START-PROC SECTION. START-PROC SECTION. 
BEGIN-PROC. BEGIN-PROC. 
ACCEPT TO-DATE ACCEPT TO-DATE 
FROM DATE. FROM DATE. 
OPEN-FILES. COPY OPENF. OPEN-FILES. COPY OPENF. 


OPEN INPUT CUST-FILE. 
OPEN I-O ORDERS. 
GET-VERSION. 
DISPLAY "VERSION?". 
ACCEPT VER-NUM. 
IF VER-NUM NOT NUMERIC 
GO TO GET-VERSION. 


INPUT-LOOP. 


READ CUST-FILE ... 


| 
: OPEN I-O WORK-FILE. | * 
| | 
| | 










Library File (OPENF.LIB) 










OPEN I-O WORK-FILE. 
INPUT-LOOP. 
OPEN INPUT CUST-FILE. READ CUST-FILE ... 
OPEN I-O ORDERS. 
GET-VERSION. 
DISPLAY "VERSION?" 
ACCEPT VER-NUM. 
IF VER-NUM NOT NUMERIC 


GO TO GET-VERSION. 













Figure 2-1 Merging Library Text 
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The COPY statement can appear anywhere that a COBOL word is allowed in 
a source program; therefore, you can use it in many ways to solve 
different problems. For example, if a library file called MTG 
contains the single entry MORTGAGE-PAYMENT-AMOUNT, it could be copied 
in the Data Division: 


Source Statement: g3 COPY MTG. PIC 999V99. 


Resulting 
Source Statement: @3 MORTGAGE-PAYMENT-AMOUNT PIC 999V99. 


or in the Procedure Division: 


Source Statement: MULTIPLY COPY MTG. BY 12 
GIVING ANNUAL-PAYMENT. 
Resulting 
Source Statement: MULTIPLY MORTGAGE-PAYMENT-AMOUNT BY 12 


GIVING ANNUAL-PAYMENT. 


The periods following the COPY statements in these examples do not 
become part of the source text. If the library text requires 
punctuation, it must be included in the library file. 


I a week yY £24240 + 


NOTE 


The two preceding examples are not 
recommended uses of the COPY statement. 
They are included only to illustrate the 
mechanics of the COBOL library facility. 


2.2.3 The COPY REPLACING Statement 


It is sometimes necessary to tailor library file text for use in a 
particular program. For example, if a record description in a library 
file has level-numbers incremented by 1 (91, O92, $3, ...) and you want 
them to be incremented by four (#1, 05, 09, ...), you can change the 
level-numbers as the library text is merged into the source program. 
During the copying process, the COPY statement can replace all 
occurrences of a literal or word with an alternate literal or word. 
For example: 


COPY ACCTREC REPLACING #2 BY §5, 
G3 BY 99, #4 BY 13. 


This sample statement causes the compiler to scan the file ACCTREC 
searching for the character-string $2. Wherever it finds a #2, the 
compiler substitutes #5. A match occurs only if the compiler finds a 
G2; no match occurs for a § or a 2 alone. The compiler follows the 
same procedure for occurrences of §3 and #4. 


The REPLACING character-string can be a literal or a _ word; it must 
compare equally, character for character, with the entire 
character-string in the library text. Table 2-1 illustrates’ the 
results of some character-string comparisons. 


REPLACING Literal 


or Word 


"W ABC" 


HRLY-RATE 


1 


15" 


"912" 


G1 


SUBTRACT 


2 


"912" 


AC 


The following examples COPY the 


CT 


Table 2-1 


contains this text: 


91 


Example 1 


Statement: 


Resul 


fl 


NmoQw 


PIC 
PIC 
PIC 
PIC 
PIC 
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"ABCD" 
HRLY-RATE 
1 

2 

mys" 

m2" 

12 
SUBTRACT 
"g12" 


ACCT1 





99. 

99 VALUE 2. 

X(5) VALUE "ABCDE". 
99V99 VALUE 3.75. 
99 VALUE @2. 


COPY NEWSBOY REPLACING B BY X. 


ts 


QHeon x 


PIC 
PIC 
PIC 
PIC 
PIC 


99. 

99 VALUE 2. 

X(5) VALUE "ABCDE". 
99V99 VALUE 3.75. 
99 VALUE #2. 


library file 


COPY REPLACING Matches 


No 
Yes 
Yes 
No 
No 
No 


No 


named NEWSBOY, which 
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Statement: 


COPY NEWSBOY REPLACING 2 BY 6. 


Result: 
gl A. 
@2 B PIC 99. 
2 cC PIC 99 VALUE 6. 
@2 D PIC X(5) VALUE "ABCDE". 
@2 E PIC 99V99 VALUE 3.75. 
G2 F PIC 99 VALUE 92. 
Example 3 
Statement: 


COPY NEWSBOY REPLACING @2 BY 63. 


Result: 
Ol aA. 
63 B PIC 99. 
63 C PIC 99 VALUE 2. 
63 D PIC X(5) VALUE "ABCDE". 
63 E PIC 99V99 VALUE 3.75. 
63 F PIC 99 VALUE 63. 


Example 4 
Statement: 
COPY NEWSBOY REPLACING B BY X, 


"ABCDE" BY "HIJ", 
3.75 BY 4.234. 


Result: 
Gl A. 
2 xX PIC 99. 
g2 cC PIC 99 VALUE 2. 
G92 D PIC X(5) VALUE "HIJ". 
G2 E PIC 99V99 VALUE 4.234. 
92 F PIC 99 VALUE #2. 


In the third example, level-number $2 was changed to level-number 63, 
which is not legal under COBOL rules; therefore, although both the 
COPY statement and the library text are syntactically correct, the 
merged text is incorrect and would generate syntax errors. 
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2.2.4 The Source Listing 


The compiler displays copied library text on the source listing; 
however, you can suppress this display by using the /NL compiler 
switch. 


Depending on how you write the COPY statement, library text can appear 
either before or after the COPY statement. The compiler normally 
prints a line of source text when it scans to the end of tthe line; 
however, when the compiler recognizes a completed COPY statement 
before the end of the line, it locates the library file, then: 


1. Prints the library text. 
2. Scans the rest of the source program line. 
3. Prints the entire source line. 


Thus, if the source line contains a COPY statement followed by other 
text (including spaces), the compiler prints the library text before 
the source line containing the COPY statement; this results in a 
somewhat confusing listing. 


You can cause the compiler to produce a more readable listing by 
making sure that you write each COPY statement as the last entry ona 
source program line. 


2.2.5 Common Errors in Using the Library Facility 
Some of the more common errors to avoid when using the library 
facility are: 


e Failing to follow the rules for the COBOL reference format 
when creating the library file. 


® Merging a library file in one format (conventional or 
terminal) with a source program written in the other. 


e Forgetting to end the COPY statement with a terminator 
period. 


e Inadvertently defining data-names in the source program when 
they are also defined in the library file, thus causing 
duplicate names. 


® Writing library file text that becomes syntactically 
incorrect when it is merged with the source program. 


e Merging the wrong library file, either because multiple 
versions exist, or because of misspellings. 


e Writing source text following the COPY statement on the same 
line, thus causing confusion in the source program listing. 


e Forgetting that numeric literals (such as @2, 77, ...) used 
in the REPLACING option replace level-numbers, picture 
descriptions, and paragraph or section names, when they find 
matches in the library file. 


e Forgetting that a period must appear in the library file if 


it is to appear in the source program; the terminator period 
that ends the COPY statement is replaced by library text. 
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2.3 USING THE PDP=11 COBOL COMPILER 
The PDP-11 COBOL compiler translates the COBOL text in a_ source 
program file into an object module that contains relocatable code, and 
an Overlay Descriptor Language (ODL) file that contains a_ structural 
description of the program. The compiler also produces an optional 
listing that contains the source statements and other information that 
you can request by using compiler switches. This section describes 
the procedure for compiling your source program; it discusses the 
COBOL command line, compiler switches and the error message summary. 
Finally, the section lists some common errors to avoid in entering 
compiler command lines. Appendix G discusses the components of the 
source program listing. 


System prompts, COBOL compiler names, and command line formats differ 
for the three supported operating systems. Table 2-2 shows the system 
prompt and compiler name for each operating system. 


Table 2-2 
Operating System Prompts and Compiler Names 





Operating System 
System 


Compiler 
Prompt Name 


J 


RSTS/E READY COBOL 
















Examples in this section are for the RSTS/E operating system. RSX-11M 
COBOL command lines are the same except for the compiler name. The 
IAS COBOL compiler command line format is described in the IAS User's 
Guide. The compiler switches described in this section can be used on 
each system. 





Depending on whether you want to compile a single source program or 
more than one, you invoke the compiler in one of two ways: 


1. To compile a single program, call for the compiler and supply 
its command line on a single line, followed by a carriage 
return; when the compilation is finished, the operating 
system prompt appears. For example: 

READY 
COBOL <command line> 


READY 
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To compile more than one program during a single execution of 
the compiler, call the compiler on one line (followed by a 
carriage return), then enter command lines in response to 
compiler prompts. When a compilation is finished, the 
compiler prompts you for the next command line. Enter a 
CTRL-Z (“Z) when the last program has been compiled: 


READY 





CBL> <command line> 
CBL> <command line> 
CBL> <command line> 


CBL> <command line> 
CBL> “2% 


PDP-11 COBOL Command Line 


The PDP-11 COBOL command line has the following format: 


<object-file>,<listing-file>=<source-file></switch>...</switch> 


where: 

<object-file> is the file specification for the file that 
is to contain the object module generated by 
the compiler. 

<listing-file> is the file specification for the file that 
is to contain the source program listing. 

<source-file> is the file specification for the file that 
contains the COBOL source program to be 
compiled. 

</switch> is a compiler switch option, written as a 


Slash (/) followed by one or more ASCII 
characters. (The next section discusses 
compiler switches.) 


You can write each file specification with or without the file type 
(or extension). If you omit the file type, the compiler assumes the 
following as defaults: 


<object-file> OBJ 
<listing-file> LST 
<source-file> CBL 
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You can omit either or both of the compiler's output files by omitting 
the corresponding file specifications from the command line. 


Consider the following examples: 
CBL> OBJECT, LIST=SOURCE 
produces OBJECT.OBJ and LIST.LST and uses SOURCE.CBL. The three files 
are assumed to be in the default directory on the default device. 
CBL> OBJECT=[7,21]SOURCE.CBS 
produces no listing-file. It uses the source-file SOURCE.CBS in 
directory [7,21] and produces OBJECT.OBJ in the default directory on 
the default device. 
CBL> ,LIST.LSX=SOURCE 
produces a listing-file (LIST.LSX) on the default device; however, no 
object-file is produced. The source-file is SOURCE.CBL. 
CBL> =SOURCE 
produces no output files at all. The source-file is SOURCE.CBL in the 
default directory on the default device. The only output of this 
compilation is the error message summary; however, it will appear 
only if the compiler detects errors. 
NOTE 
The compiler generates an ODL file only 
if it produces an object file. The ODL 


file name, device, and PPN (UIC) are the 
same as those of the object file. 


2.3.2 Compiler Switches 


PDP-11 COBOL provides a series of compile-time switches that you can 
use to select or suppress compiler options. Table 2-3 summarizes the 
compiler switches, which are then described in detail. 
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Table 2-3 
Compiler Switches 


/ACC:n Acceptable diagnostics to produce object file 
/-BOU Suppress bounds checking 

/CM6 COMPUTATIONAL-6 interpretation 

/ CREF Cross-reference listing 

/CSEG:nnnn Specify maximum procedural PSECT size 

/ CVF’ Conventional format 

/ERR:n Diagnostic print suppression 

/ HELP Display compiler command line information 
/KER:kk Specify PSECT kernel name 

/MAP Produce map on listing 

/NL Suppress listing of library text 

/ OBI Print object code locations on listing 
/-ODL Suppress ODL file generation 

/OV Overlay all procedural PSECTS 

/PFM:nn Specify maximum PERFORM nesting 

/-PLT Suppress literal pooling 

/RO Generate read-only PSECTS 

/SYM:n Add symbol table space 


/ACC:n Causes the compiler to produce an object file only if 
the source program generates diagnostics with severity 


numbers equal to or less than n. Acceptable values’ for 
n are @, 1, and 2: 






Informational diagnostics 
Warning diagnostics 
Fatal diagnostics 





bor R 


default is /ACC:l. 


Suppresses the generation of code to check that 
subscripts and indexes are in their legal ranges when 
they are used. If this switch is not specified, a 
program's use of an out-of-range subscript or index 
results in its termination by the OTS. Suppression of 
bounds checking can increase execution speed for a 
program that executes a large number of subscripted or 
indexed data references. The default is /BOU. 





If /-BOU is specified and a program uses 
out-of-range subscripts or indexes, the results 


| 

NOTE 

} 

| 

| are unpredictable. | 


| 








P| 
__ 


| /CSEG:nnnn | Specifies the maximum size for procedural PSECTs to be | 


I 
| | 
| | 


/CVE 


/ERR:n 
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pe ee ET 8 ea aay aE eee Ee eae, 
| 
/CM6 | 


Causes the compilér to interpret COMPUTATIONAL usage as 
it did in releases prior to Version 4.9. The effect is 
the same as changing all COMPUTATIONAL references’ to 
COMPUTATIONAL-6. 


NOTE 


Since COMPUTATIONAL-6 is a temporary data 
format, intended only for program conversion 
from PDP-11 COBOL releases prior to Version 4.6, 
its use for conversion purposes should also be 
considered temporary. 










Produces a cross-reference listing as part of the 
listing file. Data-names and procedure-names are listed 
in ascending order with the source program line numbers 
on which they appear. On the listing, the symbol # 
indicates the source line on which the name is defined. 


The /CREF switch significantly increases’ the 


NOTE | 
compilation time for large source programs. | 
| 


generated by the compiler; nnnn is a decimal number | 
greater than 197 that specifies the maximum PSECT size 
in bytes. 


Specifies that the source program is in conventional 
format; the compiler then expects 8f-character images 
with optional sequence numbers in character positions 
1-6, indicators in position 7, Area A beginning in 
position 8, Area B beginning in position 12, and _ the 
identification area in positions 73-89. 


Suppresses the printing of compiler diagnostic messages 
with severity numbers less than n. Acceptable values 
for n are @, 1, and 2: 


= Informational diagnostics 
1 = Warning diagnostics 

= Fatal diagnostics 
You cannot suppress fatal diagnostics. The default is 
/ERR:G@. 


Dispiays information about the compiler command line 


(including switches) on the default output device. 
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Specifies a two-character kernel for PSECT names in this 
compilation. Use this switch when two more object files 
will be merged into a single task. The Task Builder 
requires all PSECT names to be unique; specifying 
different kernels for each object file in the task 
overrides the compiler's default names and ensures 
uniqueness. 


The kernel (kk) iS a two-character string that can 
contain any combination of the letters A-Z and the 
numbers §-9. 


/MAP Causes the compiler to produce the following maps in the 
listing file: 


Data Division | 
Procedure Map | 
External Subprograms Referenced | 
Data and Control PSECTs 
OTS Routines Referenced 
Segmentation Map 

} 


Appendix G contains a description and example of each 
} map e 


/NL | Suppresses the listing of text copied from library 
files; only the COPY statement itself appears in the | 
listing file. | 

/OBI | Causes the compiler to list the object location for each | 


verb in the Procedure Division. The location appears on 
the line before the source line in which the verb is 
used. 
















i 
Specifies the maximum number of nested PERFORM | 
statements in the program being compiled. The default | 
is 18. Using this switch to specify the exact number of | 
nested PERFORMS causes the compiler to reserve no more 
memory than necessary for the PERFORM stack. | 
i 


default (/PLT), the compiler pools literals to minimize 
the space required to contain them. Depending on PSECT 
size, literal pooling can also avoid the generation of 
additional PSECTS that would otherwise result from 
reaching maximum PSECT size. However, literal pooling 
increases compile time; you can therefore speed up 


Causes the compiler to suppress literal pooling. As a 
t 

compilations by using the /-PLT switch. | 
| 
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/RO Causes the compiler to generate read-only PSECTs for 
Procedure Division object modules. The default PSECT 
access code attribute is read/write. The access code 
attribute of a PSECT affects its memory allocation by 
the Task Builder. If your system supports hardware 
memory protection, specifying read-only PSECTs can help 
avoid unintentional damage to Procedure Division code, 
especially if you compile your program with the /-BOU 
switch. You will find more information about this 
attribute in your system's Task Builder Reference 
Manual. 


NOTE 
Do not use the /RO switch if you intend to 


include the COBOL Interactive Debugger (CID) in 
the task; CID breakpoints require read/write 


PSECTs. 
/SYM:n | Causes the compiler to reserve more symbol table space | 


for the compilation. The acceptable values for n, which | 
represents the space required for the maximum number of 
data-names and procedure-names, are l, 2, 3, and 4: 





Maximum Maximum 
n Data-Names Procedure-Names 
1 761 761 
Z 1921 1921 
3 1531 1531 
4 2939 2639 


The default is /SYM:l. 


2.3.3 Error Message Summary 


If the compiler detects any errors during a compilation, it displays 
an error message summary on the system output device. The error 
message summary has the following format: 


CBL -- nnnnn ERROR(S), nnnnn FATAL 


NOTE 


If any fatal errors occur, the compiler 
does not generate an object file unless 
you use the /ACC:2 switch in the command 
line. 
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2.3.4 Common PDP-11 COBOL Command Line Errors 
Some of the more common errors to avoid when entering PDP-11l COBOL 
command lines are: 


e Omitting the /CVF switch for go0urce programs that are in 
conventional format. 


@ Including switches that contradict file specifications in the 
command line, such as using the /MAP switch when no 
listing-file is specified. 


e Omitting version numbers from file specifications, causing 
the compiler to use an unintended version of a file (on IAS 
and RSX-11M systems). 


e Forgetting to use a file type in the file specification when 
you intend to use or create a file with other than the 
default file type. 


e Forgetting to enter a comma when you want only a listing 
file. For example, CBL> ,A=A produces only a listing file, 
while CBL> A=A produces an object file and an ODL file, but 
no listing. 





2.4 THE COBOL MERGE UTILITY 


The PDP-11 COBOL compiler produces an object file and an Overlay 
Descriptor Language (ODL) file for each source file. The ODL file 
contains directives that describe the structure of the associated 
object modules; it must be supplied to the Task Builder to produce an 
executable task image that contains overlayable segments. Even when 
you do not require overlaying, you may want to supply ODL files to the 
Task Builder to combine several object modules. However, the Task 
Builder cannot directly use the compiler-generated ODL files because: 


1. The compiler-generated ODL file is not complete; it requires 
additional ODL directives to include the required I/0 
routines. 


2. The compiler generates an ODL file for each program (and 
subprogram) ; thus, multiple ODL files are required when the 
task consists of a main program that calls one or more 
subprograms. On the other hand, the Task Builder can accept 
only a single ODL file; therefore, multiple ODL files must 
first be merged. 


The Task Bulider can operate on object modules directly only if yo. 
not require overlaying and if only a few object modules combin 
produce the executable task. Section 2.5.2 describes this use of the 
Task Builder. 


oc 
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Assuming that your task is complex or does require overlaying, you 
must supply an ODL file to the Task Builder. In that case, regardless 
of the attributes of your program (and its subprograms), the 
compiler-generated ODL file(s) require merging or modification before 
the Task Builder can use them. You can merge or modify these files 
yourself if you have an in-depth knowledge of: 


1) your operating system, 
2) ODL file concepts, 


3) PDP-11 COBOL segmentation and interprogram communications, 
and 


4) the Task Builder. 


Chapter 11 (Hand-Tailoring ODL Files) describes the techniques for 
modifying ODL files yourself. However, the COBOL Merge Utility 
performs these functions for you quickly and easily in a standardized, 
systematic way. 


The Merge Utility has several options that allow you to. select 
features and tailor the resulting ODL file to fit particular needs. 
For example: 


1. You can select either a "merged" or an "abbreviated" output 
ODL file. 


The merged ODL file is a concatenation of all the input ODL 
files (that is, it contains the contents of each file, one 
directly after the other) followed by Merge-supplied ODL 
statements: 


PROG1.ODL 
PROG1.ODL 


PROG2.ODL 
PROG2.ODL 


PROG3.ODL 
PROG3.ODL 


PROGn.ODL 
PROGn.ODL 


statement 
statement 


statement 
statement 


statement 
statement 


statement 
statement 


ODL statements supplied 
by the Merge Utility 
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The abbreviated ODL file contains indirect command file 
specifications (one for each input ODL file) followed by 
Merge-supplied ODL statements: 


@PROG1.ODL 
@PROG2.ODL 
@PROG3.ODL 
@PROGn.ODL 
ODL statements supplied 
by the Merge Utility 


The merged ODL file takes more file space than the 
abbreviated ODL file; however, it is a complete ODL file, 
and the compiler-generated partial ODL files need not be 
available to the Task Builder. The abbreviated ODL takes 
less space because it contains indirect command file 
specifications; however, because the specifications are 
essentially pointers to other files, the compiler-generated 
files must also be available when you use the Task Builder. 


2. You can include the COBOL Interactive Debugger (CID) in the 
executable task. Chapter 13 describes CID and discusses its 
use. 


3. You can overlay I/O routines to reduce the size of the 
executable task; overlaying may be necessary in some cases 
to prevent address space overflow. However, if you can avoid 
overlaying I/O routines, program execution speed will be 
greater. 


4. If you elect to overlay I/O routines, the Merge Utility 
allows you to tailor I/O for the executable task. Your 
responses in the Merge dialogue specify options that balance 
execution speed against memory space. 


2.4.1 Using the Merge Utility 


Invoke the Merge Utility by typing MRG, RUN SMRG, or RUN CBLMRG 
(depending on your system) in response to a system prompt. Merge 
guides you through the specification process by asking a series of 
questions. Th dialegue sequence is affected by your answers; 
therefore, the order can vary from one use of Merge to another. 
Figures 2-2 and 2-3 show two sample Merge dialogues. 


For the purposes of this discussion, the dialogue steps are numbered. 
However, the numbers do not appear in an actual Merge dialogue. 
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PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE 

Respond with a complete or partial file specification for the 
ODL file that you will supply to the Task Builder. If you 
enter a partial specification, Merge will assume the default 
system device and directory, and the file type ODL. For 
example, if you enter PROGA, the output ODL file will be 
PROGA.ODL. The specification for this file should not 
duplicate the name of an input ODL file. Merge opens’ the 
output file immediately; using the name of an ODL file that 
you intend for input will cause that file to be lost (in the 
case of RSTS/E) or will cause an error later in the session. 


DO YOU WANT AN ABBREVIATED OR MERGED ODL FILE? 


If your response is "A" or "M", Merge generates the output ODL 
file in one of the formats described earlier. If you enter 
"H", Merge displays a short description of each type of file. 
Otherwise, Merge asks for a valid response and waits for more 
input. 


PLEASE ANSWER Y(ES) OR N(QO) 

If you enter "Y", Merge generates a directive in the ODL file 
that causes the Task Builder to. include the CID module in your 
executable task. If you enter an invalid response, Merge 
prompts you for a correction and waits for more input. 


Do not include CID if any of the object modules were compiied 
with the /RO compiler switch; CID breakpoints require 
read/write procedural PSECTs. 


CID adds approximately 1098 (decimal) words to your program's 
memory address space requirement. If the increase exceeds the 
program's size limit, you can overlay I/O routines through the 
Merge dialogue or recompile the program (for debugging 
purposes only) with the /OV switch. 


Entering "N" will cause a library of I/O routines (RMSLIB) to 
be included in your task image. Execution will be faster than 
if you overlay I/O; however, the included routines could 
cause your program's maximum size to be exceeded. If you 
enter "N", Merge continues the dialogue at Step 7. 


Entering "Y" causes Merge to ask more questions about I/0 
routine overlaying, allowing you to choose from standard 
Record Management Services (RMS) ODL files, or to specify your 
own. 


As before, an invalid response causes Merge to request a 
correction. 
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DO YOU WANT TO USE A DEC-SUPPLIED I/O OVERLAY STRUCTURE? 


eee eee eee 


Pee ee nS DU UU Aon AO 


If you answer "Y", Merge continues the dialogue at Step 7 and 
includes one of the standard RMS ODL files: 


Operating System 


RSX-11M and IAS RSTS/E 


All except INDEXED RMS11S.0DL | RMSRTS.ODL 


All RMS11X.ODL RMSRTX.ODL 
All RMS12X.ODL RMS12R.ODL 





Entering "N" allows you to specify your own ODL file _ to 
include I/O routines in the next step of the dialogue. 


If you enter "H", Merge advises you to answer "Y". Unless you 
have an ODL file to include I/O routines, and it has been 
tested and verified, you are advised to use one of the default 
files supplied with your system. 


PLEASE ENTER YOUR ODL FILE SPECIFICATION. 
Enter a file specification that includes both file name and 
file type. If either the file name or file type is missing or 
invalid, Merge asks you to re-enter the entire file 
specification. 


As in Step 1, you can enter a partial or complete file 
specification. Merge uses the same defaults as before for a 
partial file specification. After validating the file 
specification, Merge processes the input ODL file. 


OBJECT PROGRAM REFERENCED IN ODL FILE IS: 


<object-file> 
PLEASE ENTER OBJECT FILE DEVICE AND PPN IN 


THE FORMAT: DEV: [PROJECT, PROGRAMMER] 





If you enter only a carriage return, the device and PPN (or 
UIC) for the input object file are the same as the system 
defaults. However, Merge gives you the option of overriding 
the defaults by entering other specifications. 
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ANY MORE ODL FILES? 
PLEASE ANSWER Y(ES) OR N10) 





Entering "Y" causes Merge to return to Step 7 to reguest the 
name of the next input ODL file. If you enter "N", indicating 
that all ODL files have been processed, the dialogue continues 
with: 


Step 18 if Merge has detected use of indexed file 
organization, and you specified the default I/O 
overlay option in Step 5 


Step 11 if indexed I/O is not indicated in any of the 
input ODL files, or if you used a non-default 
ODL file for overlays 


DO YOU WANT THE SMALLER OR THE LARGER I/O ROUTINES? 


meee ae ee ee 


If you answer "S", Merge includes RMS11X.ODL (for RSX-11M and 
IAS systems) or RMSRTX.ODL (for RSTS/E systems). The I/0 
routines take about 9KB of user address space. 

Entering "L" causes Merge to include one of the larger ODL 
files: RMS12X.ODL (for RSX-11M and IAS systems) or RMS12R.ODL 
(for RSTS/E). These I/O routines take about 12KB of user 
address space. If you select this option and an "address 
overflow" condition is detected during task-building, merge 
the ODL files again and enter "S" to try reducing the size of 
the task. 


If you are not sure which set of routines to specify, enter 
“Ere selecting the larger I/O overlay may increase your 
program's execution speed. 


ODL FILE MERGE COMPLETE 
MERGED ODL FILE IS: <output-ODL-file> 





Merge tells you the name of the ODL file it created, which is 
the name that you entered in Step 1. If you entered a file 
specification without a file type, the actual file 
specification includes the default file type, ODL. 


After displaying this message, Merge terminates. You are then 
ready to use the Task Builder to create an executable task 
image. 


USING THE PDP-11 COBOL SYSTEM 


Figure 2-2 
Merge Dialogue Using Multiple Object Modules 
and Default I/O Overlaying 


MRG 
PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE 
PAYROL 








PAYRL1.ODL 
OBJECT FILE REFERENCED IN ODL FILE IS: 


PAYRL1.OBJ 
PLEASE ENTER OBJECT FILE DEVICE AND PPN IN 





| 

THE FORMAT: DEV: [PROJECT, PROGRAMMER] 
<CR> 
ANY MORE ODL FILES? 
PLEASE ANSWER Y(ES) OR N(O) 
Y 
PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE | 
PAYRL2 = 
OBJECT FILE REFERENCED IN ODL FILE IS: | 

PAYRL2.OBJ 

PLEASE ENTER OBJECT FILE DEVICE AND PPN IN 

THE FORMAT: DEV: [PROJECT, PROGRAMMER] | 
<CR> | 
ANY MORE ODL FILES? 
PLEASE ANSWER Y(ES) OR N(O) 
NO 


DO YOU WANT THE SMALLER OR THE LARGER I/O ROUTINES? 


Cee ee ea ee nana arene ieee En Seay 


PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE 


SL 


ODL FILE MERGE COMPLETE 
MERGED ODL FILE IS: PAYROL 
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Figure 2-3 
Merge Dialogue Using One Object Module 
and No I/O Overlaying 


MRG 
PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE 
PRSNEL.ODL 


WANT AN ABBREVIATED OR MERGED ODL FILE? 





PLEASE ANSWER Y(ES) OR N(O) 


N 

PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE 
PERSNL.ODL 

OBJECT FILE REFERENCED IN ODL FILE IS: 


PERSNL. OBJ 
PLEASE- ENTER OBJECT FILE DEVICE AND PPN IN 





THE FORMAT: DEV: [PROJECT, PROGRAMMER] | 
<CR> | 








ANY MORE ODL FIL 
PLEASE ANSWER Y( OR N(O) 
N 

ODL FILE MERGE COMPLETE 


MERGED ODL FILE IS: PRSNEL.ODL 


tty 








2.4.2 Merge Utility Error Messages 


When the Merge Utility detects an error, it displays an error message, 
then waits for another entry from you if it can recover from the 
error. The error messages are self-explanatory in most cases; this 
section lists Merge error messages that require further explanation. 


THIS ODL FILE CONTAINS A ;COBMAIN LINE 
A ;COBMAIN LINE HAS ALREADY OCCURRED 
THIS ODL FILE IS IGNORED 


A ;COBMAIN line in an ODL file identifies the 
object program as amain program. A task image 
can contain only one main program; therefore, 
Merge ignores the ODL file. 


If you specified the incorrect ODL file, continue 
the dialogue by entering the correct file 
Specification. It is possible that the PROCEDURE 
DIVISION USING phrase was omitted from the 
Subprogram that is referenced in the ODL file; in 
that case, change the program, recompile it, and 
use the Merge Utility again. Of course, this 
condition could also exist in an ODL file that was 
incorrectly modified. 
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MULTIPLE ;COBKER HEADER LINE DETECTED 
THIS ODL FILE IS IGNORED 


The ;COBKER line in an ODL file specifies the 
two-character kernel that particularizes PSECT 
names in the referenced object file. Only one 
;COBKER line is allowed; therefore, Merge ignores 
the ODL file. 


The most likely cause for this condition is 
incorrect modification of the ODL file. 


MULTIPLE ;COBOBJ HEADER LINE DETECTED 
THIS ODL FILE IS IGNORED 


The ;COBOBJ line identifies the object file for 
which the ODL file is produced. Merge assumes 
that the ODL file is incorrect because a 
compiler-generated ODL file contains only one 
;COBOBJ header line. 


NOT STANDARD COBOL ODL FILE 
FILE IS IGNORED 


The ODL file contains nonstandard ODL lines. The 
file was probably modified incorrectly. 


OPEN UNSUCCESSFUL 


The Merge Utility could not open a file for one of 
the following reasons: 


1. The device is not on line. 

2. The device is not mounted. 

3. A hardware failure occurred. 

4. The file does not exist on the device. 


5. Access to the file is not allowed. 


Determine and correct the condition; then, invoke 
the Merge Utility again. 
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READ ERROR -- MUST ABORT 

The Merge Utility encountered an unrecoverable 
error while attempting to read the input ODL file. 
Merge terminates after closing the input and 
output ODL files. The error occurred for one of 
the following reasons: 

1. The device is not on line. 

2. The device is not mounted. 

3. A hardware failure occurred. 


4. The volume is full. 


Determine and correct’ the condition; then, 
execute the Merge Utility again. 


2.5 TASK-BUILDING PDP-11 COBOL PROGRAMS 


Compiler-generated object modules contain relocatable code; they must 
be linked by the Task Builder (TKB) to create executable task images. 


The Task Builder's input can be either: 
a) a Single ODL file, or 


b) one or more object files and one or more library files. 


On RSTS/E and RSX-11M systems, invoke the Task Builder by entering 
TKB. The Task Builder displays the prompt, 


TKB> 


and waits for you to enter a TKB command line. The next two sections 
discuss two forms of the TKB command line, each of which corresponds 
to one of the input file options just mentioned. Section 2.5.3 
summarizes the factors that determine program task size. 


On IAS systems, enter the command line as described in the next two 
sections. 


2.5.1 Using ODL-File Input 


You must supply an ODL file to TKB if you want overlaying in the’ task 
image. However, you can use TKB with an ODL file regardless of 
overlay requirements. 


The ODL file, which the Merge Utility created or which the compiler 
generated and you modified, contains directives to _ TKB; the 
directives cause TKB to include component object modules and library 
modules and to create an executable image with a specified overlay 
structure. 
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RSTS/E and RSX-11M Users: 


When the TKB prompt appears, enter the command line in the following 
format: 


<task-file>,<map-file>=<ODL-file>/MP 


where: 
<task-file> is the file specification for the task image file 
to be generated. If you do not specify a file 
type, TKB uses the default extension, TSK. 
<map-file> is the file specification for the file to contain 
the optional map listing. If you omit the file 
type, TKB uses the default extension, MAP. If you 
do not want a map file, do not enter either the 
comma or the file specification. 
<ODL-file> is the file specification for the input ODL file. 
If you do not specify a file type, TKB assumes the 
default extension, ODL. 
/MP is the required switch that identifies the 
preceding file specification as an ODL file. 
The Task Builder validates the contents of the command line. TE” at 


detects no errors, TKB displays the following message and prompt: 


ENTER OPTIONS: 
TKB> 





NOTE 


The Task Builder may display the MTKB> 
prompt after you enter the command line. 
You can continue with the dialogue by 
entering a slash (/), or you can end the 
dialogue by entering two slashes (//) if 
you do not want to specify any TKB 
options. 





The RSTS/E user enters HISEG=RMS11, which causes TKB to associate the 
task image with the RSTS/E RMS11 run-time system. TKB then again 
displays its prompt: TKB>. 


\ point, enter // to end the dialogue, or enter other options 
d by // when you have entered all options and a new prompt 
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NOTE 


The most likely options you will use are 
UNITS and ASG. Your system's Task 
Builder Reference Manual describes all 
TKB options. 


Consider the following example of running TKB on a RSTS/E system: 
READY 


TKB 

TKB> PAYROL, PAYPRG=PAYROL/MP 
ENTER OPTIONS: 

KB> HISEG=RMS11 

KB> UNITS=9 

KB> ASG=SY:7,9,MT1:8 

KB> // 





| 
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Vv 
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READY 


This dialogue causes TKB to use the ODL file, PAYROL.ODL, to produce a 
task image, PAYROL.TSK, and a map in fiie PAYPRG.MAP. The UNITS 
option specifies that the task image requires three additional logical 
units (LUNS); six is the default. The ASG option assigns LUNs 7 and 


9 to the system disk and LUN 8 to magtape l. 


IAS Users: 


On IAS systems, enter the LINK command: 
LINK/OVERLAY:<ODL-file>/MAP:<map-file>/TASK:<task-file> 


If you do not include the /TASK qualifier, the Task Builder generates 
a task file with the same name as the ODL file and the default 
extension, TSK. If you omit the /MAP qualifier, the Task Builder 
produces no map file. Use the /OPTIONS qualifier to enter Task 
Builder options. 


The IAS Task Builder Reference Manual describes all qualifiers and 
options. 


2.5.2 Using Object-File Input 


The Task Builder can use object files and library files directly 
(without an ODL file) if you do not need segment overlaying in the 
task image. Therefore, you can sometimes bypass the Merge Utility 
process by using the Task Builder as described in this section. 


USING THE PDP-11 COBOL SYSTEM 


RSTS/E and RSX-11M Users: 


Enter the TKB command line in the following format: 
<task-file>,<map-file>=<object>,<object>,...,LB:CID,LB:COBLIB/LB,LB:RMSLIB/LB 


where: 
<task-file> is the file specification for the task image file 
to be generated. If you do not specify a file 


type, TKB uses the default extension, TSK. 


<map-file> is the file specification for the file to contain 
the optional map listing. If you omit the file 
type, TKB uses the default extension, MAP. If you 
do not want a map file, do not enter the comma or 
the file specification. 


<object> is a file specification for the files containing 
the object modules to be linked. You can enter 
one or more object file specifications. If you 
omit the file type, TKB assumes the default object 
file extension, OBJ. 


LB:CID is the file specification for the optional COBOL 
Interactive Debugger (CID). It must appear before 
the COBLIB specification if you wish to include 
CID. 


LB:COBLIB is the file specification for the COBOL library 
file, which contains the COBOL object-time system 
(OTS). 


LB:RMSLIB is the file specification for the RMS-1l library 
file, which contains the RMS I/O routines. 


/LB is the Task Builder switch that identifies the 
preceding file as a library file. 


After you enter the command line, the dialogue continues as described 
in Section 2.5.1. 


NOTE 
For RSX-11M users, the format of the 


command line is the same, except that 
"ILB:" is replaced by "[1,1]". 


USING THE PDP-11 COBOL SYSTEM 


IAS Users: 


Enter the Task Builder command line in the following format: 
LINK <object>,<object>,...,LB:[1,1]CID,LB: [1,1] COBLIB/LIBRARY, RMSLIB/LIBRARY 
You can enter the /MAP and /OPTIONS qualifiers as described in Section 


2.5.1. The IAS Task Builder Reference Manual describes all qualifiers 
and options. 


2.5.3 Program Task Size 





The size of a COBOL object module generated from a COBOL source file 
depends on the memory requirements for the following components: 


1. Data items in the Working-Storage Section. 
2. Number of files in the File Section. 
3. Amount of code generated for the Procedure Division. 


4. Number and length of all unique numeric and non-numeric 
literals used in the Procedure Division. 


5. Total size of all run-time modules needed for the program. 
These include arithmetic support, I/O Support, and 
segmentation support. 


6. Stack space needed to support the executabie code. 


>) 


7. Directories for all referenced data items and literals. 


If your COBOL program exceeds the memory storage size limit, the Task 
Builder displays a diagnostic message and does not produce an 
executable task. You can reduce the memory requirement by: 


1. Overlaying sections of the program by using the COBOL 
segmentation facility (See Chapter 9, Segmentation). 


2. Overlaying I/O routines (or choosing the smaller I/O routine 
option) in the Merge Utility dialogue, as described earlier 
in this chapter. 


3. Using the Merge Utility if you have not done _ so. Program 
Size is sometimes reduced because of the techniques that 
Merge uses to include run-time routines. 


2.6 EXECUTING A COBOL TASK 


When the object modules have been linked (task-built) to create an 
executable task image, you can use the RUN command to execute the 
task. If you specified SWITCH ON or OFF in the SPECIAL-NAMES 
paragraph of any COBOL sourve program in the run unit, the OTS prompts 
you to set the switches as soon as execution begins. 


USING THE PDP-11 COBOL SYSTEM 


2.6.1 The RUN Command 

Enter the RUN command in response to a system prompt: 
READY 
RUN <task-file> 


where <task-file> is the file specification for the task image. 


2.6.2 Setting Program Switches 
PDP-11 COBOL programs can test the ON/OFF status of up to 16 switches 
to determine logic paths. The switches are specified in the 
SPECIAL-NAMES paragraph in the Environment Division. When the task 
begins execution, the OTS displays the following message: 

SPECIFY "ON" SWITCHES 
You can enter a list of switch numbers (Separated by commas, spaces, 
or tab characters) or an asterisk (*). Enter a list of switch numbers 
to set specific switches; enter an asterisk (*) to set all switches. 
For example: 

2,7,16 sets switches 2, 7, and 16 


* sets all switches (1-16) 


CHAPTER 3 


NON-NUMERIC CHARACTER HANDLING 


3.1 INTRODUCTION 


COBOL programs hold their data in fields whose sizes are described in 
their source programs. These fields are thus "fixed" during 
compilation to remain the same size throughout the lifespan of the 
resulting object program. 


The data descriptions of the fields in a COBOL program describe them 
as belonging to any of three data classes -- alphanumeric, alphabetic, 
or numeric class. Numeric class data items contain only numeric 
values, alphabetic class only A-Z and space, but alphanumeric class 
data items may contain values that are all alphabetic, all numeric, or 
a mixture of alphabetic bytes, numeric bytes, or, in fact, any 


character from the ASCII character set. 


Further, these three classes are subdivided into five categories: 
alphabetic, numeric, numeric edited, alphanumeric edited, and 
alphanumeric. Every elementary item except for an index data item 
belongs to one of the classes and further to one of the categories. 
The class of a group item is treated at object time as alphanumeric 
regardless of the classes of subordinate elementary items. 


For alphabetic and numeric (data items) class and category are 
synonymous. 


An alphabetic field is a field declared to contain only alphabetic 
(A-Z and space) characters. 


An alphanumeric class field that is declared to contain any ASCII 
character is called an alphanumeric category field. 


If the data description of an alphanumeric class field specifies that 
certain editing operations will be performed on any value that is 
moved into it, that field is called an alphanumeric or numeric’ edited 
category field. 


When reading the following sections of this chapter, this distinction 
between the class or category of a data item and the actual value that 
the item contains should always be kept in mind. 


Sometimes the text refers to alphabetic, alphanumeric, and 
alphanumeric edited data items as non-numeric data items. This is to 
distinguish them from items that are specifically described as numeric 
items. 


Regardless of the class of an item, it is usually possible to store a 
value in the item, at object time, that is "illegal". Thus, 
non-numeric ASCII characters can be placed into a field described as 
numeric class, and an alphabetic class field may be loaded with 
non-alphabetic characters. 
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To increase readability, the following sections occasionally omit the 
word "class" when describing an item; however, the reader should 
regard the descriptive word, numeric, alphabetic, or alphanumeric, as 
referring to the class of an item unless it applies specifically to 
the value in the item. 


This chapter discusses non-numeric class data and the non-arithmetic, 
non-input-output operations that manipulate this type of data. 


3.2 DATA ORGANIZATION 


Usually, the data areas in a COBOL program are organized into group 
items with subordinate elementary items. A group item is a data item 
that is followed by one or more data items (elementary items) with 
higher valued level numbers. An elementary item has no higher valued 
subordinate level number. 


All of the data areas used by COBOL programs (except for certain 
registers and switches) must be described in the Data Division of the 
source program. The compiler allocates memory space for these fields 
and fixes them in size at compilation time. 


The following sub-sections (3.2.1 and 3.2.2) discuss, on a_e general 
level, how the compiler handles group and elementary data items. 


3.2.1 Group Items 


The size of a group item is the total size of the data area occupied 
by its subordinate elementary items. The compiler considers group 
items to be alphanumeric DISPLAY items. Thus, the software 
Manipulates group items as if they had been described as PIC X() 
items, and ignores the structure of the data contained within them. 


3.2.2 Elementary Items 


The size of an elementary item is determined by the number of 
allowable symbols it contains that represent character positions. For 
example, consider the following fields: 


01 TRANREC. 
03 FIELD-1 PIC X(7). 
03 FIELD-2 PIC S9(5)V99. 





Figure 3-1 
Field Sizes 


Both fields consume seven bytes of memory; however, FIELD-1l contains 
seven alphanumeric bytes while FIELD-2 contains decimal digits and an 
operational sign. Although certain verbs handle these two classes of 
data differently, the data, in either case, occupies seven bytes of 
PDP-11 memory. COBOL operations on such fields are independent of the 
mapping of the field into PDP-11l memory words (16-bit words that hold 
two 8-bit bytes). Thus, a field may begin in the left or right-hand 
byte of a word with no effect on the function of any operations that 
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In effect, the compiler sees memory as a continuous array of bytes, 
not words. This becomes particularly important when declaring a table 
with the OCCURS clause (see Chapter 5, Table Handling). 


Records (a 01 level entry and all of its subordinate entries) and data 
items that have a level number of 77 and all literal values given in 
the Procedure Division automatically begin on even byte addresses. 


I/O verbs require that records be aligned on word boundaries because 
the PDP-1l COBOL file system reads and writes integral numbers of 
words. 


Non-input-output verbs do not require alignment of the data. However, 
when two fields are aligned identically, the processing verb can 
sometimes increase its efficiency by processing them a word at a time 
rather that a byte at a time. 


In all cases, automatic word alignment of literals, records, and/or 77 
items increase the opportunity for more efficient processing. 


3.3 SPECIAL CHARACTERS 


COBOL allows the user to manipulate any of the 128 characters of the 
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ASCII character set as alphanumeric data even though many of the 
characters are control characters, which usually control input/output 
devices. Generally, alphanumeric data manipulations are performed in 
a manner that attaches no "meaning" to an 8-bit byte. Thus, the user 
can move and compare these control characters in the same manner as 
alphabetic and numeric characters. 


Although the object program can manipulate all ASCII characters, 
certain control characters cannot appear in non-numeric literals since 
the compiler uses them to delimit the source text. Further, the 
keyboards of the console and keypunch devices have no convenient input 
key for many of the special characters, thus making it difficult to 
place them into non-numeric literals. 


Special characters may be placed into data fields of the object 
program by placing the binary value of the special character into a 
numeric COMP field and redefining that field as alphanumeric DISPLAY. 
Consider the following example of redefinition. (Keep in mind that 
the even byte of a word corresponds to the low-order bits of a binary 
word.) 


LF-COMP PIC 999 COMP VALUE 10. 
LF REDEFINES LF-COMP PIC xX. 
HT-COMP PIC 999 COMP VALUE 9. 


TAB REDEFINES HT-COMP PIC X. 
CR-COMP PIC 999 COMP VALUE 13. 
CR REDEFINES CR-COMP PIC X. 





Figure 3-2 
Redefining Special Characters 


The sample coding in Figure 3-2 introduces each character as a 1-word 
COMP item with a decimal value, then redefines it as a single byte. 
(The second byte of the redefinition need not be described at the 01 
level, since redefinition at this level does not require identically 
sized fields.) 
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The following ASCII code chart may be used to determine the decimal 
value for any ASCII character. To use the chart, find the desired 
character; then add its row and column values together to determine 
the decimal integer to be supplied as a VALUE for the computational 
item. 


Column 
Value 


000 008 016 | 024 032 040 048 O56 | 064 072 | 080 088 | 096 104 112 120 
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Figure 3-3 
ASCII Code Chart 


3.4 TESTING NON-NUMERIC FIELDS 


3.4.1 Relation Tests 


An IF statement that contains a relation condition (greater-than, 
less-than, equal-to, etc.) can compare the value in a non-numeric data 
item with another value and use the result to alter the flow of 
control in the program. 


An IF statement with a relation condition compares two operands, 
either of which may be an identifier or a literal, except that both 
cannot be literals. If the relation exists between the two operands, 
the relation condition has a truth value of true. 


Figure 3-4 illustrates the general format of a relation condition. 
(The relational characters ">," "<," and "=," although required, are 
not underlined to avoid confusion with other symbols’ such as 
greater-than-or-equal-to.) 


| IS [NOT] GREATER THAN | 


: spo eat. IS [NOT] LESS THAN : eT ee 
Peon - l)rs [Nor] EQUAL TO rogeeaed : 
| | aeienmar ro-eupesseioncil nen ; arithmetic-expression-2 
Is [NOT] = J 
Figure 3-4 


Relation Condition 


| 


| 
| 
| 
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When coding a relational operator, leave a space before and after each 
reserved word. When the reserved word NOT is present, the software 
considers it and the next key word or relational character to be one 
relational operator that defines the comparison. Figure 3-5 shows the 
meanings of the relational operators. 


OPERATOR MEANING 


[NOT] aor THAN The first operand is greater than 
[NOT] (or not greater than) the second operand. 


IS [NOT] LESS THAN The first operand is less than 
Is [NOT] < (or not less than) the second operand. 


[NOT] Beet TO i first operand is equal to 
ie oe (or not equal to) the second operand. 


Figure 3-5 
The Meanings of the Relational Operators 





3.4.1.1 Classes of Data - COBOL allows comparison of both numeric 
class operands and non-numeric class operands; however, it handles 


each class of data slightly differently. For example, it allows a 
comparison of two numeric ered regardless of the formats specified 
in their respectiv USAGE lauses, but requires that all other 


comparisons (including Sonparicone of any group items) be between 
operands with the same usage. It compares numeric class operands with 
respect to their algebraic values and non-numeric (or a numeric and a 
non-numeric) class operands with respect to a specified collating 
sequence. 


If only one of the operands is numeric, it must be an integer data 
item or an integer literal and it must be DISPLAY usage; further, the 
Manner in which the software handles numeric operands depends on _ the 
non-numeric operand. Consider the following two types of non-numeric 
operands: 


1. If the non-numeric operand is an elementary item or a 
literal, the software treats the numeric operand as if it had 
been moved into an alphanumeric data item (which is the same 
size as the numeric operand) and then compared. This causes 
any operational sign, whether carried as a separate character 
Or aS an overpunch, to be stripped from the numeric item; 
thus, it appears to be an unsigned quantity. In addition, if 
the picture-string of the numeric item contains trailing P 
characters indicating that there are assumed integer 
positions that are not actually present, these are filled 
with zero digits during the operation of stripping any sign 
that is present. Thus, an item with a picture-string of 
S9999PPP is moved to a temporary location where it is 
described with a picture-string of 9999999. If its value is 
4323 (-4321), the value in the temporary location will be 
4321000. The numeric digits, stored as ASCII bytes, take 
part in the comparison. 


2. If the non-numeric operand is a roup item, the software 
treats the numeric operand as if it had been moved into a 
group item (which is the same size as the numeric operand) 
and then compared. This is equivalent to a "group move" 
The software ignores the description of the numeric field 
(except for length) and, therefore, includes any operational 
sign, whether carried as a separate character or as an 
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overpunch, in its length. (Overpunched characters are never 
ASCII numeric digits, but characters in the range of from A 
through R, {, or }.) Thus, the sign and the digits, stored as 
ASCII bytes, take part in the comparison, and zeroes are not 
supplied for P characters in the picture-string. 


The compiler will not accept a comparison between a non-integer 
numeric operand and a non-numeric operand, and any attempt to compare 
these two items will cause a diagnostic message at compile time. 


3.4.1.2 The Comparison Operation - If the two operands are 
acceptable, the software compares them byte for byte starting at their 
left-hand end. It proceeds from left to right, comparing the 
characters in corresponding character positions until it either 
encounters a pair of unequal characters or reaches the right-hand end 
of the longer operand. 


If the software encounters a pair of unequal characters, it considers 
their relative position in the collating sequence. The operand with 
the character that is positioned higher in the collating sequence is 
the greater operand. 


If the operands have different lengths, the comparison proceeds as 
though the shorter operand were extended on the right by sufficient 
ASCII spaces (040) to make them both the same length. 


If all of the pairs of characters compare equally, the operands are 
equal. 


3.4.2 Class Tests 


An IF statement that contains a class condition (NUMERIC or 
ALPHABETIC) can test the value in a non-numeric data item (USAGE 
DISPLAY only) to determine if it contains numeric or alphabetic data 
and use the result to alter the flow of control in the program. 


Figure 3-6 illustrates the general format of a class condition. If 
the data item consists entirely of the ASCII characters 0123456789 
with or without the operational sign, the class condition would 
determine that it is NUMERIC. If the item consists entirely of the 
ASCII characters A through Z and space, the class condition would 
Getermine that it is ALPHABETIC. 


NUMERIC 
identifier IS [NOT] 


ALPHABETIC 





Class Conditi 
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When the reserved word, NOT, is present, the software considers it and 
the next key word as one class condition that defines the class test 
to be executed; for example, NOT NUMERIC is a truth test for 
determining if an operand contains at least one non-numeric byte. 


If the item being tested was described as a numeric data item, it may 
only be tested as NUMERIC or NOT NUMERIC. (For further information on 
using class conditions with numeric items, see Chapter 4.) The NUMERIC 
test cannot examine an item that was described either as alphabetic or 
aS a group item containing elementary items whose data descriptions 
indicate the presence of operational signs. 


3.5 DATA MOVEMENT 


COBOL provides three statements (MOVE, STRING, and UNSTRING) that 
perform most of the data movement operations required by 
business-oriented programs. The MOVE statement simply moves data from 
one field to another. The STRING statement concatenates a series of 
sending fields into a single receiving field. The UNSTRING statement 
disperses a single sending field into multiple receiving fields. Each 


has its uses and its limitations. This section discusses data 
movement situations which take advantage of the versatility of these 


statements. 


The MOVE statement handles the majority of data movement operations on 
character strings. However, the MOVE statement has limitations in its 
ability to handle multiple fields; for example, it cannot, by itself, 
concatenate a series of sending fields into a single receiving field 
or disperse a single sending field into several receiving fields. 


Two MOVE statements will, however, bring the contents of two fields 
together into a third (receiving) field if the receiving field has 
been "subdivided" with subordinate elementary items that match the two 
sending fields in size. If other fields are to be concatenated into 
the third field and they differ in size from the first two fields, 
then the receiving field will require additional subdivisions (through 
redefinition). 


Another method of concatenation with the MOVE statement is to 
subdivide the receiving field into single character fields, creating a 
"table" of a single character field that occurs as many times as there 
are characters in the receiving field, and execute a data movement 
loop which moves each sending field, a character at a time, using a 
subscript that moves continuously across the receiving field. 


Two MOVE statements can also be used to disperse the contents of one 
sending field to several receiving fields. The first MOVE statement 
can move the left-most end of the sending field to a receiving field; 
then the second MOVE statement can move the right-most end of the 
sending field to another receiving field. (The second receiving field 
must first be described with the JUSTIFIED clause.) Characters from 
the middle of the sending field cannot easily be moved to any 
receiving field without extensive redefinitions’of the sending field 
Or a character-by-character movement loop (as with concatenation). 


The concatenation and dispersion limitations of the MOVE statement are 
handled quite easily by the STRING and UNSTRING statements. The 
following sections (3.6, 3.7, and 3.8) discuss these three statements 
in detail. 
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3.6 THE MOVE STATEMENT 


The MOVE statement moves the contents of one field into another. The 
following illustration shows the two formats of the MOVE statement. 


Format 1 


MOVE FIELD1 TO FIELD2 


MOVE CORRESPONDING FIELD1 TO FIELD2 


NOTE 


Format 2 is discussed in Section 3.6.6. 





FIELD1 is the name of the sending field and FIELD2 is the name of the 
receiving field. The statement causes the software to move the 
contents of FIELD] into FIELD2. The two fields need not be the same 


Size, class, or usage; and they may be either group or elementary 
items. If the two fields are not the same length, the software will 
align them on one end or the other -- and will truncate or pad (with 


spaces) the other end. The movement of group items and non-numeric 
elementary items is discussed below. 


A point to remember when using the MOVE statement is that it will 
alter the contents of every character position in the receiving field. 


3.6.1 Group Moves 


If either the sending or receiving field is a group item, the software 
considers the move to be a group move. It treats both the sending and 
receiving fields in a group move as if they were alphanumeric class 
fields. If the sending field is a group item and the receiving field 
is an elementary item, the software ignores the receiving field 
description (except for the size description, in bytes, and any 
JUSTIFIED clause); therefore, the software conducts no conversion or 
editing on the receiving field. 


3.6.2 Elementary Moves 


If both fields of a MOVE statement are elementary items, their data 


description clauses control their data movement. (If the receiving 
field was described as numeric or numeric edited, the rules for 
numeric moves -- see Chapter 4, Numeric Character Handling -- control 


the data movement.) 


MS y 


The following table shows :the legal (and illegal) non-numeric 
elementary moves. 
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Table 3-1 
Legal Nen-Numeric Elementary Moves 


SENDING FIELD CATEGORY RECEIVING FIELD CATEGORY 


ALPHABETIC ALPHANUMERIC 
ALPHANUMERIC EDITED 


ALPHABETIC | Legal 


ALPHANUMERIC Legal 
ALPHANUMERIC EDITED Legal 


NUMERIC INTEGER 
(DISPLAY ONLY) Tllegal 


NUMERIC EDITED Tllegal 





In all of the legal moves shown above, the software treats the sending 
field as though it had been described as PIC X(). If the sending 
field description contains a JUSTIFIED clause, the clause will have no 
effect on the move. If the sending fieid picture-string contains 
editing characters, the software uses them only to determine the 
field's size. 


Numeric class data must be in DISPLAY (byte) format and must be an 
integer. 


If the description of the numeric data item indicates the presence of 
an operational sign (either as a character or an overpunch) or if 
there are P characters in the picture-string of the numeric data item, 
the software first moves the item to a temporary location. During 
this move, it removes the sign and fills out any P character positions 
with zero digits. It then uses the temporary value (which may be 
shorter than the original if a separate sign were removed, or longer 
if P character positions were filled in with zeroes) as the sending 
field as if it had been described as PIC X(), that is, as if its 
category were alphanumeric. 


If the sending item is an unsigned numeric class field with no P 
characters in its picture-string, the software does not move the item 
to a temporary location. 


A numeric integer data item sending field has no effect on _ the 
justification of the receiving field. If the numeric sending field is 
shorter than the receiving field, the software fills the receiving 
field with spaces. : 


In legal, non-numeric elementary moves, the receiving field actually 
controls the movement of data. All of the following items, in the 
receiving field, affect the move: (1) the size, (2) the presence of 
editing characters in its description, and (3) the presence of the 
JUSTIFIED RIGHT clause in its description. The JUSTIFIED clause and 
editing characters are mutually exclusive; therefore, the two classes 
are discussed separately below. 


When a field that contains no editing characters or JUSTIFIED clause 
in its description is used as the receiving field of a non-numeric 
elementary MOVE statement, the statement moves the characters by 
starting at the left-hand end of the fields and scanning across, 
character-by-character to the right. If the sending item is’ shorter 
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than the receiving item, the software fills the remaining character 
positions with spaces. 


3.6.2.1 Edited Moves - Alphabetic or alphanumeric fields may contain 
editing characters. Consider the following insertion editing 
characters. Alphabetic fields will accept only the B- character; 
however, alphanumeric fields will accept all three characters. 


B -- blank insertion position 
0 -- zero insertion position 
/ -~ slash insertion position. 


When a field that contains an insertion editing character in its 
picture-string is used as the receiving field of a non-numeric 
elementary MOVE statement, each receiving character position that 
corresponds to an editing character receives the insertion byte value. 
Figure 3-7 illustrates the use of such symbols with the statement, 
MOVE FIELD1 TO FIELD2. (Assume that FIELD1 was described as PIC 
X(7).) 












FIELD2 
FIELD1 PICTURE~STRING CONTENTS AFTER MOVE 


070476 XX/99/XX 07/04/76 









04JUL76 99BAAAB99 04 JUL 76 












2351212 XXXBXXXX/XX/ 235 1212/° / 





123456 OXBOXBOXBOX 01 02 03 04 





Figure 3-7 
Data Movement with Editing Symbols 


Data movement always begins at the left end of the sending field, and 
moves only to the byte positions described as A, 9, or X in the 
receiving field picture-string. When the sending field is exhausted, 
the software supplies space characters to fill any remaining character 
positions (not insertion positions) in the receiving field. If the 
receiving field becomes exhausted before the last character is moved 
from the sending field, the software ignores the remaining sending 
field characters. 


3.6.2.2 Justified Moves - A JUSTIFIED RIGHT clause in the data 
description of the receiving field causes the software to reverse its 
usual data movement conventions. (It starts with the right-hand 
characters of both fields and proceeds from right to left.) If the 
sending field is shorter than the receiving field, the software fills 
the remaining left-hand character positions with spaces. Figure 3-8 
illustrates various data description situations for the statement, 
MOVE FIELD1 TO FIELD2, with no editing. 
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FIELD1 FIELD2 


PICTURE-STRING [| CONTENTS PICTURE-STRING | CONTENTS AFTER 
(AND JUST CLAUSE) MOVE 


XX 


AXXXX 


XX JUST 


XXXXX JUST 





Figure 3-8 
Data Movement with No Editing 


3.6.3 Multiple Receiving Fields 


If a MOVE statement is written with more than one receiving field, it 
moves the same sending field value to each of the receiving fields. 


It has essentially the same effect as a series of separate MOVE 
statements that all have the same sending field. (For information on 
subscripted fields, see section 3.6.4.) 


The receiving fields need have no relationship to each other. The 
software checks the legality of each one independently, and performs 
an independent move operation on each one. 


Multiple receiving fields on MOVE statements provide a convenient way 
to set many fields equal to the same value, such as during 
initialization code at the beginning of a section of processing. For 
example: 


MOVE SPACES TO LIST-LINE, EXCEPTION-LINE, NAME-FLD. 
MOVE ZEROES TO EOL-FLAG, EXCEPT-FLAG, NAME-FLAG. 


MOVE 1 TO COUNT-1, CHAR-PTR, CURSOR. 


3.6.4 Subscripted Moves 


Any field of a MOVE statement may be subscripted and the referenced 
field may also be used to subscript another name in the same 
statement. 


When more than one receiving field is named in the same MOVE 
statement, the order in which the software evaluates the subscripts 
affects the results of the move. Consider the following two 
Situations: 


Situation 1 MOVE FIELDI1(FIELD2) TO FIELD2 FIELD3. 


Situation 2 MOVE FIELD1 TO FIELD2 FIELD3(FIELD2). 





Figure 3-9 
Subscripted MOVE Statements 
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In Situation 1, the software evaluates FIELDI(FIELD2) only once, 
before it moves any data to the receiving fields. In effect it is as 
if the statement were replaced with the following statements: 


MOVE FIELD1(FIELD2) TO TEMP. 
MOVE TEMP TO FIELD2. 
MOVE TEMP TO FIELD3. 


In situation 2, the software evaluates FIELD3(FIELD2) immediately 
before moving the data into it (but after moving the data from FIELDI1 
to FIELD2). Thus, it uses the newly stored value of FIELD2 as_ the 
subscript value. In effect, it is as if the statement were replaced 
with the following statements: 


MOVE FIELD1 TO FIELD2. 


MOVE FIELD1 TO FIELD3(FIELD2). 


3.6.5 Common Errors, MOVE Statement 


A most important thing to remember when writing MOVE statements is 
that the compiler considers any MOVE statement that contains a group 
item to be a group move. It is easy to forget this fact when moving a 
group item to an elementary item, and the elementary item contains 
editing characters, or a numeric integer. These attributes of the 
receiving field (which would determine the action of an elementary 
move) have no effect on the action of a group move. 


3.6.6 Format 2 - MOVE CORRESPONDING 


Format 2 of the MOVE statement allows the programmer to move multiple 
elementary items from one group item to another, by using a single 
MOVE statement. When the corresponding phrase is used, selected 
elementary items in the sending field are moved to those elementary 


items in the receiving field whose data-names are identical, For 
example: 
01 A-GROUP 01 B-GROUP 
02 FIELDL 02 FIELD2 
03 A PIC x 03 A PIC x 
03 B PIC 9 03 C PIC xx 
03 C PIC xx 03 E PIC xxx 
03 D PIC 99 


03 EB PIC xxx 
MOVE CORRESPONDING A-GROUP TO B~-GROUP 
OR 


MOVE CORRESPONDING FIELD] TO FIELD2 
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The above examples are equivalent to the following series of MOVE 
statements: 
MOVE A OF FIELDI1 TO A OF FIELD2 
MOVE C OF FIELDI1 TO C OF FIELD 2 


MOVE E OF FIELDI1 TO E OF FIELD2 


3.7 THE STRING STATEMENT 


The STRING statement concatenates the contents of two or more’ sending 
fields into a single field. 


The statement has many forms; the simplest is equivalent, in 
function, tO a non-numeric MOVE statement. Consider the following 
illustration; if the two fields are the same size, or if the sending 
field (FIELD1) is larger, the statement is equivalent to the 
statement, MOVE FIELD] TO FIELD2. 





Figure 3-10 
Sample STRING Statement 


If the sending field is shorter than the receiving field, an important 
difference between the STRING and MOVE statements emerges: the 
software does not fill the receiving field with spaces. Thus, the 
STRING statement may leave some portion of the receiving field 
unchanged. 


Additionally, the receiving field must be an elementary alphanumeric 
field with no JUSTIFIED clause or editing characters in its 
description. Thus, the data movement of the STRING statement always 
fills the receiving field from left-to-right with no editing 
insertions. 


3.7.1 Multiple Sending Fields 


An important characteristic of the STRING statement is its ability to 
concatenate a series of sending fields into one receiving field. 
Consider the following example of the STRING statement: 


STRING FIELDIA FIELD1B FIELD1IC DELIMITED BY SIZE 


INTO FIELD2. 





Figure 3-11 
Concatenation with the STRING Statement 


In this sample STRING statement, FIELD1A, FIELD1B, and FIELDIC are all 
sending fields. The software moves them to the receiving field 
(FIELD2) in the order in which they appear in the statement, from left 
to right, resulting in the concatenation of their values. 
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If FIELD2 is not large enough to hold all three items, the operation 
stops when it is full. If this occurs while moving one of the sending 
fields, the software ignores the remaining characters of that field 
and any other sending fields not yet processed. For example, if 
FIELD2 became full while receiving FIELD1B, the software would ignore 
the rest of FIELDIB and all of FIELDIC. 


If the sending fields do not fill the receiving field, the operation 
stops with the movement of the last character of the last sending item 
(FIELD1IC in Figure 3-11). The software does not alter the contents 
nor space-fill the remaining character positions of the receiving 
field. 


The sending fields may be non-numeric literals and figurative 
constants (except for ALL literal). For example, the following 
statement sets up an address label with the literal period and _ space 
between the STATE and ZIP fields: 


STRING CITY SPACE STATE ". " ZIP 


DELIMITED BY SIZE INTO ADDRESS-LINE. 





Figure 3-12 
Literals as Sending Fields 


Sending fields may also be subscripted. For example, the following 
statement uses subscripts to concatenate the elements of a table 
(A-TABLE) into a single field (A-FOUR). (I, of course, must be a 
subscript or an index~-name.) 


STRING A-TABLE(I) A-TABLE(I+1) A-TABLE(I+2) A-TABLE(I+3) 
DELIMITED BY SIZE INTO A-FOUR. 


Figure 3-13 
Indexed Sending Fields 





3.7.2 The POINTER Phrase 


Although the STRING statement normally starts at the left-hand end of 
the receiving field, with the POINTER phrase it is possible to start 
it scanning at another point within the field. (The scanning, 
however, remains left-to-right.) 


| MOVE 5 TO P. | 
S | 


TRING FIELDIA FIELDIB DELIMITED BY SIZE 
| INTO FIELD2 WITH POINTER P. | 
PFS chsh sts MORES Av ncsenesnsennwnancwemmanssn) 
Figure 3-14 
Sample POINTER Phrase 


When the POINTER phrase is used, the value of P determines’ the 
Starting character position in the receiving field. In Figure 3-14, 
the 5 in P causes the software to move the first character of FIELDIA 
into character position 5 of FIELD2 (the left-most character position 
of the receiving field is character position 1) and leave positions 1 
through 4 unchanged. 
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When the STRING operation is complete, the software leaves P pointing 
to one character position beyond the last character replaced in the 
receiving field. If FIELDIA and FIELDIB in Figure 3-14 are both four 
characters long, P will contain a value of 13 (5+4+4) when the 
operation is complete (assuming that FIELD2 is at least 12 characters 
long). 


3.7.3 The DELIMITED BY Phrase 


Although the sending fields of the STRING statement are fixed in size 
at compile time, they frequently contain variable-length items that 
are padded with spaces. For example, a 20-character city field may 
contain only the word MAYNARD and 13 spaces. A valuable feature of 
the STRING statement is that it may be used to move only the useful 
data from the left-hand end of the sending field. The DELIMITED BY 
phrase, written with a data-name or literal, instead of the word SIZE, 
performs this operation. (The delimiter may be a literal, a data 
item, a figurative constant, or the word SIZE. It may not be ALL 
literal since ALL literal has an indefinite length. When the phrase 
contains the word SIZE, the software moves each sending field, in 
total, until it either exhausts the sending field, or fills the 


Consider the following example: 


STRING CITY SPACE STATE ". "™ ZIP 


DELIMITED BY SIZE INTO ADDRESS-LINE. 





Figure 3-15 
Delimiting with the Word SIZE 


If CITY is a 20-character field, the result of the STRING operation 
shown in Figure 3-15 might look like the following: 


AYER MA. 01432 


Race ake spaces 


A far more attractive printout can be produced by having the STRING 
operation produce the following: 


AYER, MA. 01432 


To accomplish this, use the figurative constant SPACE as a delimiter 
on the sending field; thus, 


MOVE 1 TO P. 
STRING CITY DELIMITED BY SPACE 
INTO ADDRESS-LINE WITH POINTER P. 


STRING ", " STATE ". " ZIP 
DELIMITED BY SIZE 
INTO ADDRESS-LINE WITH POINTER P. 





Figure 3-16 
SPACE as a Delimiter 
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This sample coding uses the pointer's characteristic of pointing to 
one character position beyond the last character replaced in the 
receiving field to enable the second STRING statement to begin at a 
position one character past where the first STRING statement stopped. 
(The first STRING statement moves data characters until it encounters 
a space character -- a match of the delimiter SPACE. The second 
STRING statement adds the literal, the 2-character STATE field, 
another literal, and the 5-character ZIP field.) 


The delimiter can be varied for each field within a single STRING 
statement by repeating the DELIMITED BY phrase after the sending field 
names to which it applies. Thus, the following shorter statemen has 
the same effect as the preceding example. (Placing the operands on 
separate source lines, as shown in this example, has no effect on the 
operation of the statement, but improves program readability and 
simplifies debugging.) 


STRING CITY DELIMITED BY SPACE 
Ww ; " STATE W - W 


ZIP DELIMITED BY SIZE 
INTO ADDRESS-LINE. 





Figure 3-17 
Repeating the DELIMITED BY Phrase 


The sample STRING statement in Figure 3-17 cannot handle 2-word city 
names, such as New York, since the software would consider the space 
between the two words as a match for the delimiter SPACE. A longer 
delimiter, such as two or three spaces (non-numeric literal), can 
solve this problem. Only when a sequence of characters matches’ the 
delimiter will the movement stop for that data item. With a 2-byte 
delimiter, the same statement can be rewritten in a simpler form: 


STRING CITY ", " STATE ". " ZIP 


DELIMITED BY " " INTO ADDRESS-LINE. 





Figure 3-18 
Delimiting with More Than One Space Character 


Since only the CITY field may contain two consecutive spaces (the 
entire STATE field is only two bytes long), the delimiter's search of 
the other fields will always be unsuccessful and the effect is the 


same as moving the full field (delimiting by SIZE). 


Data movement under control of a data-name or literal is generally 
slower in execution speed than movement delimited by SIZE. 


The example in Figure 3-18 illustrates a frequent source of error in 
the use of STRING statements to concatenate fields. The remainder of 
the receiving field is not sSpace-filled as with a MOVE statement. Bl 
ADDRESS-LINE is to be printed on a mailing label, for example, the 
STRING statement should be preceded by the statement, MOVE SPACES TO 
ADDRESS-LINE. This guarantees a space fill to the right of the 
concatenated result. Alternatively, the last field concatenated by 
the STRING statement can be a field previously set to SPACES. (This 
sending field must be moved under control of a delimiter other than 
SPACE, of course.) 


Ww 
{ 


ba 
cn 
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3.7.4 The OVERFLOW Phrase 


When the SIZE option of the DELIMITED BY phrase controls the STRING 
operation and the pointer value is either known or the POINTER phrase 
is not used, the programmer can tell, by simple addition, if the 
receiving field is large enough to hold the sending fields. However, 
if the DELIMITED BY phrase contains a literal or an identifier, or if 
the pointer value is not predictable, it may be difficult to tell 
whether the size of the receiving field is adequate, and an overflow 
May occur. 


Overflow occurs when the receiving field is full and the software is 
either about to move a character from a sending field or is 
considering a new sending field. Overflow may also occur if, during 
the initialization of the statement, the pointer contains a value that 
is either less than 1 or greater than the length of the receiving 
field. In this case, the software moves no data to the receiving 
field and terminates the operation immediately. 


The ON OVERFLOW phrase at the end of the STRING statement tests for an 
overflow condition: 


| 


Figure 3-19 
The ON OVERFLOW Phrase 


The ON OVERFLOW phrase cannot distinguish the overflow caused by a bad 
initial value in pointer PNTR from the overflow caused by a receivin 
field that is too short. Only a separate test, preceding the STRING 
statement, can distinguish between the two. 


The following examples illustrate the overflow condition: 


DATA DIVISION. 


O01 FIELDI1A PIC XXX VALUE "ABC". 
Ol FIELD2 PIC XXxXxX. 


PROCEDURE DIVISION. 


STRING FIELDIA QUOTE DELIMITED BY SIZE INTO FIELD2. 
STRING FIELDIA FIELD1A DELIMITED BY SIZE INTO FIELD2. 
STRING FIELDIA FIELDIA DELIMITED BY "C" INTO FIELD2. 
STRING FIELDIA FIELD1A FIELDIA FIELDIA 

DELIMITED BY "B" INTO FIELD2. 
STRING FIELDIA FIELDIA "C" DELIMITED BY "C" 

INTO FIELD2. 
MOVE 2 TO P. 
STRING FIELDI1A "AC" DELIMITED BY "C" 

INTO FIELD2 WITH POINTER P. 





Figure 3-20 
Various STRING Statements 
Illustrating the Overflow Condition 
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The results of executing the numbered statements follow: 


Table 3-2 
Results of the 
Preceding Sample Statements 


| oveetiowt 


a 
a 
a 
ee ee 
re 






Value of FIELD2 after 
the STRING operation 












ABAB 
AABA 


3.7.5 Subscripted Fields in STRING Statements 


All data-names used in the STRING statement may be subscripted, and 
the pointer value may be used as a subScript. 


Since the pointer value might be used as a subscript on one or more of 
the fields in the statement, it is important to understand the order 
in which the software evaluates the subscripts and exactly when it 
updates the pointer. (The use of the pointer as a subscript is not 
specified by ANS-74 COBOL. Before using it, read the note at the end 
of this subsection.) 


The software updates the pointer after it moves the last character out 
of each sending field. Consider the following sample coding: 





MOVE 1 TO P. 

STRING "ABC" 
SPACE 
"DEF" DELIMITED BY SIZE 
INTO R WITH POINTER P. 


Figure 3-21 
STRING Statement with Pointer 


During the movement of "ABC" into the receiving field (R), the pointer 
value remains at 1. After the move, the software increases the 
pointer value by 3 (the size of the sending field literal "ABC") and 
it takes on the value 4. The software then moves the figurative 
constant SPACE and increases the pointer value by 1 and it takes on 
the value 5. "DEF" is then moved and, on completion of the move, the 
software increases the pointer to its final value for this operation, 
By 
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Now, consider the updating characteristics of the pointer when applied 
to subscripting: 


MOVE 1 TO P. 
STRING CHAR (P) 
CHAR (P) 


CHAR (P) 
CHAR(P) DELIMITED BY SIZE 
INTO R WITH POINTER P. 





Figure 3-22 
Subscripting with the Pointer 


If CHAR is a l-character field in a table, the pointer increases by 
one after each field has been moved and the software will move them 
into R as if they had been subscripted as CHAR(1), CHAR(2), CHAR(3), 
and CHAR(4). If CHAR is a 2-character field, the pointer increases by 
two after each field has been moved and the fields will move into R as 
if they had been subscripted as CHAR(1), CHAR(3), CHAR(5), and 
CHAR(7). 
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The software evaluates the subscript of a receiving item only once, at 
the start of the STRING operation. Therefore, if the pointer is used 
aS a subscript on the receiving field, changes occurring to. the 
pointer during the execution of the STRING statement will not alter 
the choice of which receiving string is altered. 


Even the delimiter fiel can be subscripted, and it too can be 
subscripted with the pointer. The software re-evaluates the delimiter 
subscript once for each sending field, immediately before it compares 
the delimiter to the field. Thus, by subscripting it with the pointer 
value, the delimiter can be changed for each sending field. This has 
the peculiar effect of choosing the next sending field's delimiter 
based on the position, in the receiving field, into which its first 
character will fall. For example, consider the following sample 
coding: 


01 DTABLE. 
03 D PIC X OCCURS 7 TIMES. 


MOVE 1 TOP. 


STRING "ABC" 
i ABC " 
"ABC" DELIMITED BY D(P) 
INTO R WITH POINTER P. 





Figure 3-23 
Subscripting the Delimiter 
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The following table shows the value that will arrive in the receiving 


field 


(R) from the three "ABC" literals if DTABLE contains the values 


shown in the left-hand column: 


Table 3-3 
Results of the 
Preceding Sample Statements 


ABCDEFG (Unchanged) 


BCDEFGH AABABC 
CDEFGHI ABABCABC 


CCCOCCCE ABABAB 





34726 


NOTE 


The rules in this section, concerning 
subscripts in the STRING statement, are 
rules that are not specified by 1974 
American National Standard COBOL. 
Dependence on these rules, particularly 
those involving the use of the pointer 
field as a subscript, may produce 
programs that will not perform the same 
way on other COBOL compilers. 


If the pointer field is not used as a 
subscript on any of the fields in the 
statement, the point at which the 
software evaluates the subscripts is 
immaterial to the execution of the 
statement. Thus, by avoiding the use of 
the pointer as a subscript, uniform 
results can be expected from all COBOL 
compilers that adhere to 1974 ANS COBOL. 


Common Errors, STRING Statement 


The most common errors made when writing STRING statements are: 


using the word "TO" instead of "INTO" 
forgetting to write “DELIMITED BY SIZE"; 
forgetting to initialize the pointer; 
initializing the pointer to 0 instead of 1; 


forgetting to provide for space fill of the receiving field 
when it is desirable. 
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3.8 THE UNSTRING STATEMENT 


The UNSTRING statement disperses the contents of a single sending 
field into multiple receiving fields. 


The statement has many forms; the simplest is equivalent in function 
to a non-numeric MOVE statement. Consider the following illustration; 
the sample statement is equivalent to MOVE FIELD1 TO FIELD2, 
regardless of the relative sizes of the two fields. 


UNSTRING FIELD1 INTO FIELD2. 


Figure 3-24 
Sample UNSTRING Statement 


The sending field (FIELD1) may be either a group item or an 
alphanumeric, or alphanumeric edited elementary item. The receiving 
field (FIELD2) may be alphabetic, alphanumeric, or numeric, but it 
cannot specify any type of editing. 


If the receiving field is numeric, it must be DISPLAY usage. The 
picture-string of a numeric receiving field may contain any of the 
TaAanal wnvmarin AR arr iNntAAN AR avanrtbarae a2yverant Fre D arr af mAs ees Lh 
acyat £LUliwhL LE UO OVUL tverivil LLIGALAYL LOLS Exceper ror #8 allug,g VL CUULDSES, Lil 
editing characters. The UNSTRING statement moves the sending field to 
numeric receiving fields as if the sending field had been described as 
an unsigned integer; further, it automatically truncates or zero 


fills as required. 


If the receiving field is not numeric, the software follows the rules 
for elementary non-numeric MOVE statements. It left-justifies the 
data in the receiving field, truncating or space-filling as required. 
(If the data-description of the receiving field contains a JUSTIFIED 
clause, the software right-justifies the data, truncating or 


space-filling to the left as required.) 


3.8.1 Multiple Receiving Fields 


An important characteristic of the UNSTRING statement is its ability 
to disperse one sending field into several receiving fields. Consider 
the following example of the UNSTRING statement written with multiple 
receiving fields: 


UNSTRING FIELD1 INTO 


FIELD2A FIELD2B FIELD2C. 





Figure 3-25 
Multiple Receiving Fields 


In this sample statement, FIELD1 is the sending field. The software 
performs the UNSTRING operation by scanning across FIELD] from left to 
right. When the number of characters scanned is equal to the number 
of characters in the receiving field, the software moves the scanned 
characters into the receiving field and begins scanning the next group 
of characters for the next receiving field. 
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Assume that each of the receiving fields in the preceding illustration 
(FIELD2A, FIELD2B, and FIELD2C) is five characters long, and that 
FIELD1 is 15 characters long. The size of FIELD2A determines’ the 
number of characters for the first move. The software scans across 
FIELD] until the number of characters scanned equals the size of 
FIELD2A (5). It then moves those first five characters to FIELD2A, 
and sets the scanner to the next (sixth) character position in FIELD]. 
The size of FIELD2B determines the size of the next move. The 
software begins this move by scanning across FIELD1 from character 
position six, until the number of scanned characters equals the size 
of FIELD2B (5). It then moves the sixth through the tenth characters 
to FIELD2B, and sets the scanner to the next (eleventh) character 
position in FIELD1. FIELD2C determines the size of the last move (for 
this example) and causes characters 11 through 15 of FIELDI1 to be 
moved into FIELD2C, thus terminating this UNSTRING operation. 


Each data movement acts as an individual MOVE statement, the sending 
field of which is an alphanumeric field equal in size to the receiving 
field. If the receiving field is numeric, the move operation will 
convert the data to the numeric form. For example, consider what 
would happen if the fields under discussion had the data descriptions 
and were manipulating the values shown in the following table: 


Table 3-4 
Values Moved Into the Receiving Fields 
Based on the Value in the Sending Field 


FIELD1 FIELD2A FIELD2B FIELD2C 
PIC X(15). PIC X(5) PIC S9(5) PIC S999V99 
VALUE IS: LEADING SEPARATE 


ABCDE1234512345 +12345 


XXXXX0000100123 +00001 





FIELD2A is an alphanumeric field and, therefore, the software simply 
conducts an elementary non-numeric move with the first five 
characters. 


FIELD2B, however, has a leading separate sign that is not included in 
its size. Thus, the software moves only five numeric characters and 
generates a positive sign in the separate sign position. 


FIELD2C has an implied decimal point with two character positions to 
the right of it, plus an overpunched sign on the low-order digit. The 
sending field should supply five numeric digits; but, Since the 
sending field is alphanumeric, the software treats it as an unsigned 
integer; it truncates the two high-order digits and supplies two zero 
digits for the decimal positions. Further, it supplies a positive 
overpunch sign, making the low-order digit a +0 (or the ASCII 
character, { ). (There is no simple way to have UNSTRING recognize a 
sign character or a decimal point in the sending field.) 


If the sending field is shorter than the sum of the sizes of the 
receiving fields, the software ignores the remaining receiving fields. 
If it reaches the end of the sending field before it reaches the end 
of one of the receiving fields, the software moves the scanned 
characters into that receiving field. It left-justifies and fills the 
remaining character positions with spaces for alphanumeric data, or 
decimal point aligns and zero fills the remaining character positions 
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for numeric data. Consider the following examples of a sending field 
that is too short. (The statement is UNSTRING FIELD] INTO FIELD2A 
FIELD2B. FIELD2A is a 3-character alphanumeric field, and receives 
the first three characters of FIELD1 (ABC) .in every operation. 
FIELD2B, however, runs out of characters every time before filling. 
Since FIELD2A always contains the characters ABC, it is not shown.) 


Table 3-5 
Handling a Sending Field that is Too Short 


FIELD1 FIELD2B FIELD2B 
PIC X(6) PICTURE IS: Value after UNSTRING Operation 
VALUE IS: 


ABC246 


| LEADING SEPARATE 





$9999 ie 


3.8.2 The DELIMITED BY Phrase 


The size of the data to be moved can be controlled by a delimiter, 
rather than by the size of the receiving field. The DELIMITED BY 
phrase supplies the delimiter characters. 


UNSTRING delimiters are quite flexible; they can be literals, 
figurative constants (inciuding ALL literal), or identifiers 
(identifiers may even be subscripted data-names). This sub-section 
discusses the use of these three types of delimiters. Subsequent 
sections cover multiple delimiters, the COUNT phrase, and the 
DELIMITER phrase. Subscripting delimiters is discussed at the end of 
this section under Subscripted Fields in UNSTRING Statements. 


Consider the following sample UNSTRING statement; it uses the 
figurative constant, SPACE, as a delimiter: 


| UNSTRING FIELD1 DELIMITED BY SPACE INTO FIELD2. | 


Figure 3-26 
Delimiting with a Space Character 


In this example, the software scans the sending field (FIELD1), 
searching for a space character. If it encounters a space, it moves 
all of the scanned (non-space) characters that precede that space to 
the receiving field (FIELD2). If it finds no space character, it 
moves the entire sending field. When it has determined the size of 
the sending field, the software moves the contents of that field 
following the rules for the MOVE Statement, truncating or zero filling 
as required. 


The following table shows the results of an UNSTRING operation that 
delimits with a literal asterisk (UNSTRING FIELD1 DELIMITED BY "*" 
INTO FIELD2). 
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Table 3-6 
Results of Delimiting with an Asterisk 


FIELD1 FIELD2 FIELD2 
PIC X(6) PICTURE IS: VALUE AFTER 
VALUE IS: UNSTRING 


KKKEKKK | 


XXX 
sagen | me 


| 2geree | 


12345* $9999 SEPARATE 2345+ 
TRAILING 


2468%** $999V9 SEPARATE +4680 
LEADING 





If the delimiter matches the first character in the sending field, the 
software considers the size of the sending field to be zero. The 
movement operation still takes place, however, and fills the receiving 
field with spaces or zeroes depending on its class. 


A delimiter may also be applied to an UNSTRING statement that has 
multiple receiving fields: 


UNSTRING FIELD1 DELIMITED BY SPACE 
INTO FIELD2A FIELD2B. 


Figure 3-27 
Delimiting with Multiple Receiving Fields 





The sample instruction in Figure 3-27 causes the software to scan 
FIELD1 searching for a character that matches the delimiter. If it 
finds a match, it moves the scanned characters to FIELD2A and sets the 
scanner to the next character position to the right of the character 
that matched. It then resumes scanning FIELD] for a character that 
Matches the delimiter. Tf it finds a match, it moves all of the 
Characters that lie between the character that first matched the 
delimiter and the character that matched on the second scan, and sets 
the scanner to the next character position to the right of the 
character that matched. (The DELIMITED BY phrase could handle 
additional receiving fields in the same manner as it handled FIELD2B.) 


The following table shows the results of an UNSTRING operation that 
applies a delimiter to multiple receiving fields (UNSTRING FIELD1 
DELIMITED BY "*" INTO FIELD2A FIELD2B). 
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Table 3-7 
Results of Delimiting 
Multiple Receiving Fields 


VALUES AFTER UNSTRING OPERATION 
FIELD2A FIELD2B 
PIC X(3) PIC X(3) 


A*B*¥*X*** 


A*BCDEFG | 











FIELD1 
PIC X(8) 
VALUE IS: 



















| ABC**DEF © ABC AAA | 


KEKRKEB Romp sales 


nz 
A 





The last two examples illustrate the limitations of a single character 
delimiter. Accordingly, the delimiter may be longer than one 
character and it may be preceded by the word ALL. 


The following table shows the results of an UNSTRING operation that 
uses a 2-character delimiter (UNSTRING FIELD1 DELIMITED BY "**" INTO 
FIELD2A FIELD2B) : 


Table 3-8 
Results of Delimiting 
with Two Asterisks 


FIELDI VALUES AFTER UNSTRING OPERATION 









PIC X(8) FIELD2A FIELD2B 
VALUE IS: PIC XXX PIC XXX 
JUSTIFIED 





AB**C¥D* *D* 


oe an ee 


AB***Cp* | ABA CD* 
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Unlike the STRING statement, the UNSTRING statement accepts the ALL 
literal as a delimiter. When the word ALL precedes the delimiter, the 
action of the UNSTRING statement remains essentially the same as with 
one delimiter until the scanning operation finds a match. At this 
point, the software scans farther, looking for additional consecutive 
strings of characters that also match the delimiter item. Lt 
considers the "ALL delimiter" to be one, two, three, or more adjacent 
repetitions of the delimiter item. 


The following table illustrates the results of an UNSTRING operation 
that uses an ALL delimiter (UNSTRING FIELD] DELIMITED BY ALL "*" INTO 
FIELD2A FIELD2B). 


Table 3-9 
Results of Delimiting 
with ALL Asterisks 


















VALUES AFTER UNSTRING OPERATION 
FIELD2A FIELD2B 
PIC XXX PIC XXX 
JUSTIFIED 


FIELD1 
PIC X(8) 
VALUE IS: 














ABC *DEF* 


ce 
i 


The next table illustrates the results of an UNSTRING operation that 
combines ALL with a 2-character delimiter (UNSTRING FIELD] DELIMITED 
BY ALL "**" INTO FIELD2A FIELD2B). 








Table 3-10 
Results of Delimiting with 
ALL Double Asterisks 


FIELD] VALUES AFTER UNSTRING OPERATION 


PIC X(8) PIC XXX 
VALUE IS: JUSTIFIED 





A®R*kD*** | 
ARRKEKKK 
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In addition to unchangeable delimiters, such as literals and 
figurative constants, delimiters may be designated by identifiers. 
Identifiers (which may even be subscripted data-namés) permit variable 
delimiting. Consider the following sample statement: 


UNSTRING FIELD1 DELIMITED BY DEL1 
INTO FIELD2A FIELD2B. 


Figure 3-28 
Delimiting with an Identifier 


The data-name, DEL1, must be alphanumeric. It may be a group or 
elementary item, and it may be edited. (Since the delimiter is not a 
receiving field, any editing characters will not effect its use, other 
than contributing to the size of the item.) 


If the delimiter contains a subscript, the subscript may be varied as 
a side effect of the UNSTRING operation. The evaluation of subscripts 
is discussed later in this section. 


3.8.2.1 Multiple Delimiters - The UNSTRING statement has the ability 
to scan a sending field, searching for a match froma list of 
delimiters. This list may contain ALL delimiters and delimiters of 
various sizes. The only requirement of the list is that delimiters 
must be connected by the word OR. 


The following sample statement Separates a sending field into three 
receiving fields. The sending field consists of three strings 
separated by the following: (1) any number of spaces, or (2) a comma 
followed by a single space, or (3) a Single comma, or (4) a tab 
character, or (5) a carriage return character. (The ", " must precede 
the "," in the list if it is ever to be recognized.) 


UNSTRING FIELD] DELIMITED BY 
ALL SPACE OR 
W - " OR 


Ww ; " OR 

TAB OR 

CR 

INTO FIELD2A FIELD2B FIELD2C. 





Figure 3-29 
Multiple Delimiters 


The following table illustrates the potential of this statement. The 
tab (represented by the letter t) and carriage return (represented by 
the letter r) characters represent single character fields containing 
the ASCII horizontal tab and carriage return characters. 
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Table 3-11 
Results of the Multiple Delimiters 
Shown in Figure 3-29 


FIELD2B 
PIC 9999 


0000 





















FIELD1 
PIC X(12) 







FIELD2A 
PIC XXX 


FIELD2C 
PIC XXX 





A,0,Cr 

At456,AE 
AAAA 3AAA9 9AA 
AttBr 





ABCD ,A4321,2 ABC 4321 ZAA 


t--tab character, r--carriage return character 


3.8.3 The COUNT Phrase 


The COUNT phrase keeps track of the size of the sending string and 
stores the length in a user-supplied data area. 


The length of a delimited sending field may vary widely (from zero to 
the full length of the field) and some programs may require knowledge 
of this length. For example, if it exceeds the size of the receiving 
field (which is fixed in size) some data may be truncated and the 
program's logic may require this information. 


To use the phrase, simply follow the receiving field name with the 
words COUNT IN and an identifier. Consider the following sample 
statement: 


UNSTRING FIELD1 DELIMITED BY ALL "*" 
INTO FIELD2A COUNT IN COUNT2A 


FIELD2B COUNT IN COUNT2B 
FIELD2C. 





Figure 3-30 
The COUNT Phrase 


In this sample statement, the software will count the number of 
characters between the left-hand end of FIELD] and the first asterisk 
in FIELD] and place that value into COUNT2A; thus, COUNT2A contains 


the size of the first sending string. The software does not include 
the delimiter in the count (as it is not a part of the string). 


The software then counts the :number of characters in the second 
sending field and places that value into COUNT2B. 


The phrase should be used only where needed; in this example the 
length of the string moved to FIELD2C is not needed, so no COUNT 
phrase follows it. 
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If the receiving field is shorter than the value placed in the count 
field, the software truncates the sending string. (If the number of 
integer positions in a numeric field is smaller than the value placed 
into the count field, high-order numeric digits have been lost.) 


If the software finds a delimiter match on the first character it 
examines, it places a zero in the count field. 


The count field must be described as a numeric integer, either COMP or 
DISPLAY usage, with no editing symbols nor the character P in its 
picture-string. The software moves the count value into the count 
field according to the rules for an elementary numeric MOVE statement 


The COUNT phrase may be used only in conjunction with the DELIMITED BY 
phrase. 


3.8.4 The DELIMITER Phrase 


The DELIMITER phrase causes the actual character or characters’ that 
delimited the sending field tc be stored in a user-supplied data area. 
This phrase is most useful when: (1) the statement contains a 
delimiter list, (2) any one of the items in the list might have 
delimited the field, and (3) program logic flow depends on which one 
found a match. In fact, the DELIMITER and COUNT phrases could be used 
together and program logic flow could depend on both the size of the 
sending string and the delimiter character that terminated it. 


To use the DELIMITER phrase, simply follow the receiving field name 
with the words DELIMITER IN and an identifier. (The software places 
the delimiter character in the area named by the identifier.) Consider 
the following sample UNSTRING statement: 


UNSTRING FIELD1 DELIMITED BY "," OR TAB OR 
ALL SPACE OR CR 


INTO FIELD2A DELIMITER IN DELIMA 
FIELD2B DELIMITER IN DELIMB 
FIELD2C. 





Figure 3-31 
The DELIMITER Phrase 


After moving the first sending string to FIELD2A, the software takes 
the character (or characters) that delimited that string and places it 
in DELIMA. DELIMA, then, contains a comma, or a tab, or a carriage 
return, or any number of spaces. Since the delimiter string is moved 
under the rules of the elementary non-numeric MOVE statement, the 
software truncates or space fills with left or right justification 
(depending on its data description). 


The software then moves the second sending string to FIELD2B_ and 
places its delimiting character into DELIMB. 


When a sending string is delimited by the end of the sending field 
(rather than a match on a delimiter) the delimiter string is of zero 
length. This causes the DELIMITER item to be space filled. The 
phrase should be used only where needed; in this example, the 
character that delimits the last sending string is not needed, so no 
DELIMITER phrase follows FIELD2C. 
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The data item named in the DELIMITER phrase must be described as an 
alphanumeric item. It may contain editing characters and it may even 
be a group item. 


When the DELIMITER and COUNT phrases are used together, they must 
appear in the correct order (DELIMITER phrase preceding the COUNT 
phrase). Both of the data items named in these phrases may be 
subscripted or indexed. If they are subscripted, the subscript may be 
varied as a side effect of the UNSTRING operation. (The evaluation of 
subscripts is discussed in section 3.8.8.) 


3.8.5 The POINTER Phrase 


Although the UNSTRING statement normally starts at the left-hand end 
of the sending field, the POINTER phrase permits the user to select a 
character position in the sending field for the software to begin 
scanning. (The scanning, however, remains left-to-right.) 


When a sending field is to be dispersed into multiple receiving 
fields, it often happens that the choice of delimiters, the size of 
subsequent receiving fields, etc. depend on the value in the first 
sending string or the character that delimited that string. Thus, the 
program may need to move the first field, hold its place in the 
sending field, and examine the results of the operation to determine 
how to handle the sending items that follow. This is done by using an 
UNSTRING statement with a POINTER phrase that fills only the first 
receiving field. When the first string has been moved to a_ receiving 
item, the software updates the pointer data item with a new position 
(one character beyond the delimiter that caused the interruption) to 
begin the next scanning operation. The program may then examine the 
new position, the receiving field, the delimiter value, the sending 
String size, and resume the scanning operation by executing another 
UNSTRING statement with the same sending field and pointer data item. 
Thus, the UNSTRING statement can move one sending string at a time, 
with the form of each move being dependent on the context of the 
preceding string of data. 


The POINTER phrase must follow the last receiving item in the 
statement. Consider the following two UNSTRING statements with their 
accompanying POINTER phrases and tests: 


MOVE 1 TO P. 
UNSTRING FIELD1 DELIMITED BY 


| *:" OR TAB OR CR OR ALL SPACE ! 
INTO FIELD2A 
DELIMITER IN DELIMA 
COUNT IN LSIZEA 
WITH POINTER PNTR. 
0 GO TO NO-LABEL-PROCESS. | 
| 
| 


IF LSIZEA 

IF DELIMA 

NTR > 8 GO TO BIG-LABEL-PROCESS 
TO LABEL-PROCESS. 

GO TO BAD-LABEL PROCESS. 


coe 
ten i 
n 
Hoty 
m © & 
(o) 


IF DELIMA A 


i 
| 


| UNSTRING FIELD1 DELIMITED BY ... WITH POINTER pre. | 


Figure 3-32 
The POINTER Phrase 
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PNTR contains the current position of the scanner in the sending 
field. The second UNSTRING statement uses PNTR to begin scanning the 
additional sending strings in FIELD]. 


Since the software considers the left-most character to be character 
position one, the value returned by PNTR may be used to examine the 
next character. To do this, simply use PNTR as a subscript on _ the 
sending field (providing that the sending field is also described as a 
table of characters). For example, consider the following sample 
coding: 


01 FIELDI. 
02 FIELD1-CHAR OCCURS 40 TIMES. 


UNSTRING FIELD1 
WITH POINTER PNTR. 
IF FIELDI-CHAR(PNTR) = "X" ... 





Figure 3-33 
Examining the Next Character 
By Using the Pointer Data 
Item as a Subscript 


Another way to examine the next character of the sending field is to 
use the UNSTRING statement to move it to a l-character receiving 
field. Consider the following sample coding: 


| UNSTRING FIELD1 | 


WITH POINTER PNTR. 
UNSTRING FIELD1 INTO CHARI] WITH POINTER PNTR. 
SUBTRACT 1 FROM PNTR. 
LF CHARI = 9X: pae 





Figure 3-34 
Examining the Next Character 
By Placing It Into a 1-Character Field 


The program must decrement PNTR in order for this case to work like 
the one illustrated in Figure 3-33, since the second UNSTRING 
statement will increment the pointer value by l. 


The program must initialize the POINTER phrase data item before the 
UNSTRING statement uses it. The software will terminate the UNSTRING 
operation if the initial value of the pointer is less than one or 
greater than the length of the sending field. (A pointer value that 
is less than one or greater than the length of the sending field 
causes an overflow condition. Overflow conditions are discussed in 
section 3.8.7.) 


The POINTER and TALLYING phrases may be used together in the same 


UNSTRING statement; but, when both are used, the POINTER phrase must 
precede the TALLYING phrase. 
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3.8.6 The TALLYING Phrase 


The TALLYING phrase counts the number of receiving fields that 
received data from the sending field. 


When an UNSTRING statement contains several receiving fields, the 
possibility exists that there may not always be as many sending 
strings as there are receiving fields. The TALLYING phrase provides a 
convenient method for keeping a count of how many fields were acted 
upon. 
re ee ee 
MOVE O TO RCOUNT. 
UNSTRING FIELD] DELIMITED BY "," OR ALL SPACE 
INTO FIELD2A 
FIELD2B 
FIELD2C 
FIELD2D 
FIELD2E 


TALLYING IN RCOUNT. 





Figure 3-35 
The TALLYING Phrase 


If the software has moved only three sending strings when it reaches 
the end of FIELD1, it adds 3 to RCOUNT. The first three fields 
(FIELD2A, FIELD2B, and FIELD2C) contain data from the operation, and 
the last two (FIELD2D and FIELD2E) do not. 


The TALLYING data item always contains the sum of its initial contents 
plus the number of sending strings acted upon by the UNSTRING command 
just executed. Thus, the programmer may want to initialize the tally 
count before each use. 


When used in the same statement with a POINTER phrase, the TALLYING 
phrase must follow the POINTER phrase and both phrases must follow all 
of the field names, the DELIMITER and COUNT phrases. The data items 
for both phrases must contain numeric integers, that is, be without 
editing characters or the letter P in their picture-strings; both 
data items may be either COMP or DISPLAY usage. They may be signed or 
unsigned and, if they are DISPLAY usage, they may contain any desired 
Sign option. 


The data items for both phrases may be subscripted or indexed, or they 
may be used as subscripts on other fields in the statement. (The 
evaluation of subscripts is discussed in section 3.8.8.) A convenient 
use of the TALLYING phrase data item is as a subscript of a receiving 
field. Consider the following sample coding, which causes program 
control to execute the UNSTRING statement repeatedly until it exhausts 
the sending field. 


MOVE 1 TO PNTR, TLY. 
PAR1. UNSTRING FIELD1 DELIMITED BY "," OR CR 
| INTO FIELD2 (TLY) | 
DELIMITER IN DEL2 | 
WITH POINTER PNTR | 
TALLYING IN TLY. 
IF DEL2 = "," GO TO PARI. 





Figure 3-36 
The POINTER and TALLYING Phrases 


Used Together 
Nd et Ne NA We ese 
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This sample coding causes program control to loop through the UNSTRING 
statement, using the pointer, PNTR, to scan across FIELDI with 
successive executions. Each comma isolates a sending string until 
control reaches either a carriage return character or the end of 
FIELD1. If it reaches the end of the field without encountering a 
carriage return character, the software places a space into the 
delimiter field, DEL2, and control falls through the IF statement and 
out of the loop. 


Since the TALLYING data item, TLY, is increased by 1 after each data 
movement, it serves as a subscript on the receiving field. In effect 
this causes the software to unpack the value in FIELD] into an array 
of fixed-size fields. Further, an array of COUNT data items can be 
supplied and loaded by the UNSTRING/TALLYING statement by adding the 
following phrase to the coding in Figure 3-36: 


COUNT IN C(TLY) 


Figure 3-37 
Subscripting the COUNT Phrase 
With the TALLYING Data Item 


The TALLYING data item, in the above example, is one greater than the 
number of receiving fields acted upon by the UNSTRING operation. This 
is because the data item must be initialized to a value of one in 
order to be used as a subscript for the first receiving item. 


3.8.7 The OVERFLOW Phrase 


The OVERFLOW pnrase detects the overfiow condition and provides an 
imperative statement to be executed when it detects the condition. An 
overflow condition exists when either of the following two. situations 
occurs: 


1. The UNSTRING statement is about to be executed and its 
pointer data item contains a value of less than one or 
greater than the size of the sending field. When it detects 
this situation, the software executes the OVERFLOW phrase 
before it moves any data. Thus, the values of all of the 
receiving fields remain unchanged. 


2. The UNSTRING statement has filled all of the receiving fields 
and data still remains in the sending field that has not been 
matched as a delimiter or included in a sending string. When 
it detects this situation, the software executes the OVERFLOW 
phrase after it has executed the UNSTRING statement. Thus, 
the values of all of the receiving fields are updated, but 
some data has not been moved. 


If the UNSTRING operation causes the scanner to move off the end of 
the sending field (thus exhausting it), the software will not execute 
the OVERFLOW phrase. 


Consider the following set of instructions, which cause program 
control to execute the UNSTRING statement repeatedly until it exhausts 
the sending field. The TALLYING data item is a subscript indexing the 
receiving field. (Compare this loop with the one in Figure 3-36, 
which accomplishes the same thing.) 
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MOVE 1 TO TLY PNTR. 
PAR1. UNSTRING FIELD1 DELIMITED BY "," OR CR 
INTO FIELD2 (TLY) 


WITH POINTER PNTR 
TALLYING IN TLY 
ON OVERFLOW GO TO PARI. 





Figure 3-38 
Using the OVERFLOW Phrase 


NOTE 


The overflow condition also occurs if 
the value of a pointer data item lies 
outside the sending field at the start 
of execution of the UNSTRING statement. 
(The pointer value must not be less than 
l, nor greater than the length of the 
sending field.) This type of overflow is 
not distinguishable from the overflow 
condition described at the start of this 
section, except that this condition 
causes the UNSTRING statement to 
terminate before any data movement takes 
place. Then, the values of all 
receiving fields remain unchanged. 


3.8.8 Subscripted Fields in UNSTRING Statements 


Since the flexibility of the UNSTRING statement is enhanced by 
subscripting and indexing and particularly by subscripting with other 
fields within the statement (such as subscripting the receiving field 
with the TALLYING data item as discussed above), it is important to 
understand how often and exactly when the software evaluates these 
subscripts and indexes. This sub-section discusses the frequency and 
times of subscript evaluation. 


The software evaluates subscripts and indexes on the following items 
only once, at the initiation of the UNSTRING statement; thus, any 
change in subscript values during the execution of the statement has 
no effect on these fields: 

1. Sending field, 

2. POINTER data item, 

3. TALLYING data item. 
The software evaluates subscripts and indexes on the following items 
immediately before it moves data into the item. It moves the data to 
these items in the order in which they are listed in the statement 
(which is the same order as below): 

1. Receiving field, 


2. DELIMITER data item, 


3. COUNT data item. 


WwW 
' 
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The software evaluates any subscripts and indexes on the data-names in 
the DELIMITED BY phrase (delimiters) immediately before it scans each 
sending string looking for a delimiter match. Thus, it re-evaluates 
these data-names once for each receiving field in the statement. 


If any of the following items are used as subscripts on any receiving 
fields, the programmer must be aware of the point at which these items 
are updated: 


e POINTER data-item, 

e TALLYING data-item, 

® COUNT data-item, 

e Another receiving field. 


Figure 3-39 illustrates, with a flow chart, the sequence of evaluation 
operations: 
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IF COUNT PHRASE PRESENT 
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RECEIVING COUNT FIELD 
DELIMITER FIELD RECEIVING 
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FIELDS 
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Figure 3-39 
Sequence of Subscript Evaluation 
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NOTE 


The rules in this section concerning the 
exact point at which the software 
evaluates the identifiers in the 
DELIMITED BY phrase and the point at 
which it updates the POINTER and 
TALLYING data items, are rules that are 
specified by 1974 American National 
Standard COBOL, as opposed to the STRING 
statement where these are not so 
specified. 


3.8.9 Common Errors, UNSTRING Statement 
The most common errors made when writing UNSTRING statements are: 
e Leaving the OR connector out of a delimiter list; 


e Misspelling or interchanging the words, DELIMITED and 
DELIMITER; 


e Writing the DELIMITER and COUNT phrases in the wrong order 
when both are present (DELIMITER must precede COUNT); 


e Leaving out the word INTO or writing it as TO; 


@ Repeating the word INTO where it is not needed; thus: 





UNSTRING FIELD] DELIMITED BY SPACE OR TAB 
INTO FIELD2A DELIMITER IN DELIMA 


INTO FIELD2B DELIMITER IN DELIMB | 
INTO FIELD2C DELIMITER IN DELIMC. 


Figure 3-40 
Erroneously Repeating the Word INTO 


e Writing the POINTER and TALLYING phrases in the wrong order 
(POINTER must precede TALLYING). 


3.9 THE INSPECT STATEMENT 


The INSPECT statement examines the character positions in a field and 
counts or replaces certain characters (or groups of characters) in 
that field. 


Like the STRING and UNSTRING operations, INSPECT operations’ scan 
across the field from left to right; further, like those two 
statements, the INSPECT statement features a phrase which allows it to 
begin or terminate the scanning operation with a delimiter match. 
(Thus, the operation can begin within the field instead of at _ the 
left-hand end, or it may begin at the left-hand end and terminate 
within the field.) 


The TALLYING operation (which counts certain characters in the field) 
and the REPLACING operation (which replaces certain characters in the 
field) are quite versatile and may be applied to ail of the characters 
in the delimited area of the field being inspected, or they may be 
applied only to those characters that match a given character string 


res) 
1 

Lvs) 

ON 
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under stated conditions. Consider the following sample statements, 
which both cause a scan of the complete field: 


INSPECT FIELD] TALLYING TLY FOR ALL "B". 


Figure 3-41 
Sample INSPECT...TALLYING Statement 


This statement scans FIELD] looking for the character B. Each time it 
finds a B, it increments TLY by l. 


INSPECT FIELD] REPLACING ALL SPACE BY ZERO. 


Figure 3-42 
Sample INSPECT...REPLACING Statement 


This statement scans FIELD1 looking for space characters. Wherever it 
finds a space character, it replaces it with zero. 


One INSPECT statement can contain both a TALLYING phrase and a 
REPLACING phrase. However, when used together, the TALLYING phrase 
must precede the REPLACING phrase. An INSPECT statement with both 
phrases is equivalent to two separate INSPECT statements and, in fact, 
the software compiles such a statement into two distinct INSPECT 
statements. (To simplify debugging, therefore, it is best to 
initially write the two phrases in separate INSPECT statements.) 


3.9.1 The BEFORE/AFTER Phrase 


The BEFORE/AFTER phrase acts as a delimiter and (possibly) restricts 
the area of the field being inspected. 


The following sample statement would count only the zeroes’ that 
precede the percent sign (%) in FIELD1. 


INSPECT FIELD1 TALLYING TLY 


FOR ALL ZEROES BEFORE "$"., 





Figure 3-43 
Sample INSPECT...BEFORE Statement 


The delimiter (the percent sign in the preceding sample statement) can 
be a single character, a string of characters, or any figurative 
constant. Further, it can be either an identifier or a literal. 


e If the delimiter is an identifier, it must be an elementary 
data item of DISPLAY usage. It may be alphabetic, 
alphanumeric, or numeric, and, it may contain editing 
characters. The compiler always treats the item as if it had 
been described as an alphanumeric string. (It does this by 
implicit redefinition of the item, as described in Section 
3.9 6 2x:) 


e If the delimiter is a literal, it must be non-numeric. 
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The software repeatedly compares the delimiter characters against an 
equal number of characters in the field being inspected. If none of 
the characters matches the delimiter, or if insufficient characters 
remain in the field for a full comparison (at the right-hand end), the 
software considers the comparison to be unequal. 


The examples of the INSPECT statement in Figure 3-44, illustrate the 
way the delimiter character finds a match in the field being 
inspected. (The portion of the field the statement ignores as a 
result of the BEFORE/AFTER phrase delimiters is crossed out with a 
slash, and the portion it inspects is underlined.) 


INSTRUCTION FIELD1 VALUE 


INSPECT FIELD1...BEFORE "E".  ABCDEFGHY 
INSPECT FIELD1...AFTER "E". KBVPYFGHI 


INSPECT FIELD1...BEFORE "K". ABCDEFGHI 
INSPECT FIELD1...AFTER "K". KECBEYGHY 


INSPECT FIELD1...BEFORE "AB". KBCVEYGHY 
INSPECT FIELD1...AFTER "AB". KBCDEFGHI 


INSPECT FIELD1...BEFORE "HI". ABCDEFGHY 
INSPECT FIELD1...AFTER "HI". KBCBYY GUY 


INSPECT FIELD1...BEFORE "IA". ABCDEFGHI 
INSPECT FIELD1...AFTER "IA". KBCREVGHY 


The ellipsis represents the position of the TALLYING or REPLACING 
phrase. 





Figure 3-44 
Matching the Delimiter Characters 
to the Characters in a Field 


The software scans the field for a delimiter match before it scans for 
the inspection operation (TALLYING or REPLACING), thus establishing 
the limits of the operation before beginning the actual inspection. 
The importance of the separate scan is discussed further in Section 
34943 


3.9.2 Implicit Redefinition 


The software requires that certain fields referred to by the INSPECT 
statement be alphanumeric fields. If one of these fields was 
described as another data class, the compiler redefines that field so 
the INSPECT statement can handle it as a simple alphanumeric string. 
This implicit redefinition is conducted as follows: 


® If the field was described as alphabetic, alphanumeric 
edited, or unsigned numeric, the compiler simply redefines it 
as alphanumeric. This is a compile-time operation; no data 
movement occurs at object-time. 


e If the field was described as signed numeric, the compiler 
first removes the sign and then redefines the field as 
alphanumeric. If the sign is a separate character, the 
compiler ignores that character, essentially shortening the 
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field, and that character does not participate in the 
implicit redefinition. If the sign is an "overpunch" on the 
leading or trailing digit, the compiler actually removes’ the 
Sign value and leaves the character with only the numeric 
value that was stored in it. The compiler alters the digit 
position containing the sign before beginning the INSPECT 
operation and restores it to its former value after the 
operation. If the sign's digit position does not contain a 
valid ASCII signed numeric digit, the action of the 
redefinition causes the value to change. Table 3-12 shows 
these original, altered, and restored values. 


The compiler never moves an implicitly redefined item from its storage 
position. All redefinition occurs in place. 


The position of an implied decimal point on numeric quantities does 
not affect implicit redefinition. 


Table 3-12 
Original, Altered, and Restored Values Resulting 
from Implicit Redefinition 
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3.9.3 The INSPECT Operation 


Regardless of the type of inspection (TALLYING or REPLACING), the 
INSPECT statement has only one method for inspecting the characters in 
the field. This section describes this method. 


However, before discussing how the inspection operation is conducted, 
let's analyze the INSPECT statement itself: 





INSPECT FIELD1 TALLYING TLY FOR ALL "B" BEFORE "A". 
The field a The argument 
inspected 
The operation The delimiter 
phrase phrase 





Figure 3-45 
Sample INSPECT Statement 


The format of the INSPECT statement requires that a field be named 
which is to be inspected (FIELD1 above); the field name must be 
followed by an operation phrase (TALLYING TLY above); and, that 
phrase must be followed by one or more identifiers or literals ("B" 
above). These identifiers or literals comprise the "arguments" (items 
to be compared to the field being inspected). More than one argument 
makes up the "argument list". 


e TALLYING Arguments 


Each argument in an argument list can have other fields 
associated with it. Thus, each argument that is used ina 
TALLYING operation must have a tally counter (TLY above) 
associated with it. The software increments the tally 
counter each time it matches the argument with a character or 
group of characters in the field being inspected. 


e REPLACING Arguments 


INSPECT FIELD1 REPLACING ALL "0" BY "S$". 





Figure 3-46 
Sample REPLACING Argument 


Each argument in an argument list that is used in a REPLACING 
operation must have a replacement item (S$ above) associated 
with it. The software uses the replacement item to replace 
each strin of characters in the field that matches the 
argument. 


Each argument in an argument list (that is used with either a TALLYING 
Or REPLACING operation) may have a delimiter field (BEFORE/AFTER 
phrase) associated with it. If the delimiter field is not present, 
the software applies the argument to the entire field. If the 
delimiter field is present, the software applies the argument only to 
that portion of the field specified by the BEFORE/AFTER phrase. 
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3.9.3.1 Setting the Scanner - The INSPECT operation begins by setting 
the scanner to the leftmost character position of the field being 
inspected. It remains on this character until an argument has_ been 
Matched with a character (or characters) or until all arguments have 
failed to find a match at that position. 


3.9.3.2 Active/Inactive Arguments - When an argument has a 
BEFORE/AFTER phrase associated with it, that argument has a delimiter 
and may not be eligible to participate in a comparison at every 
position of the scanner. Thus, each argument in the argument list has 
an active/inactive status at any given setting of the scanner. 


For example, an argument that has an AFTER phrase associated with it 
starts the INSPECT operation in an inactive state. The delimiter of 
the AFTER phrase must find a match before the argument can participate 
in the comparison. When the delimiter finds a match, the software 
retains the character position beyond the matched character string; 
then, when the scanner reaches or passes this position, the argument 
becomes active. 


[ee ee ee SS SS SS eh 
INSPECT FIELD1 TALLYING TLY 


unm zArmmos mer oe 


FOR ALL “B” AFTER “X"., 





Figure 3-47 
Sample AFTER Delimiter Phrase 


If FIELD1 in Figure 3-47 has a value of "ABABXZBA", the argument B 
remains inactive until the scanner finds a match for the delimiter X. 
Thus, argument B remains inactive while the software scans character 
positions 1 through 5. At character position 5, the delimiter X finds 
a match, and since the character position beyond the matched delimiter 
character is the point at which the argument becomes active, argument 
B is compared for the first time at character position 6. It finds a 
successful match at character position 7 and this causes TLY to be 
incremented by l. 


The examples in Figure 3-48 illustrate other situations where the 
arguments and/or the delimiters are longer than one character. 
(Consider the sample statement to be an INSPECT...TALLYING statement 
that is scanning FIELD1, tallying in TLY, and looking for the 
arguments and delimiters in the left-hand column. Assume that TLY is 
initialized to 0.) 
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ARGUMENT AND FIELD1 ARGUMENT CONTENTS OF 
DELIMITER VALUE ACTIVE AT TLY AFTER SCAN 
POSITION 
BXBXXXXBB 6 2 
"B" AFTER "xXx" XXXXXXXX 3 0 
| BXBXBBBBXX never 0 
| BXBXXBXXB 6 2 
"XxX" AFTER "Xx" | XXXXXXXX 3 6 
BBBBBBXX never Q 
BXYBXBXX 7 0 
"B" AFTER "XB" XBXBXBXB 3 3 
BBBBBBXB never 0 
XXXXBXXXX 6 0 
"BX" AFTER "XB" XXXXBBXXX 6 1 
XXBXXXXBX 4 i 


Figure 3-48 
Where Arguments Become Active in a Field 


When an argument has an associated BEFORE delimiter, the 
inactive/active states reverse roles: the argument is in an active 
state when the scanning begins, and becomes inactive at the character 
position that matches the delimiter. Additionally, regardless of the 
presence of the BEFORE delimiter, an argument becomes inactive when 
the scanner approaches the right-hand end of the field and the 
remaining characters are fewer in number than the characters in the 
argument. (In such a case, the argument cannot possibly find a match 
in the field so it becomes inactive.) 


Since the BEFORE/AFTER delimiters are found on a separate scan of the 
field, the software recognizes and sets up the delimiter boundaries 
before it scans for an argument match; therefore, the same characters 
can be used aS arguments and delimiters in the same phrase. 


3.9.3.3 Finding an Argument Match - The software selects arguments 
from the argument list in the order in which they appear in the list. 
If the first one it selects is an active argument and the conditions 
stated in the INSPECT statement allow a comparison, the software 
compares it to the character at the position of the scanner. If the 
active argument does not find a match, the software takes the next 
active argument from the list and compares that to the same character. 
If none of the active arguments finds a match, the scanner moves one 
position to the right and begins the inspection operation again with 
the first active argument in the list. The inspection operation 
terminates at the right-hand end of the field. 


When an active argument does find a match, the software ignores any 
remaining arguments in the list and conducts the TALLYING or REPLACING 
operation on the character. The scanner moves to a new position and 
the next inspection operation begins with the first argument in the 
list. (The INSPECT statement may contain additional conditions, which 
are described later in this section; this discussion, however, 
assumes that the argument match is allowed to take place and that 
inspection is allowed to continue following the match.) 
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The software updates the scanner by adding the size of the matching 
argument to it. This moves the scanner to the next character beyond 
the string of characters that matched the argument. Thus, once an 
active argument matches a string of characters, the statement does not 
inspect those character positions again unless program control 
executes the entire statement again. 


3.9.4 Subscripted Fields in INSPECT Statements 


Any identifier named in an INSPECT statement may be subscripted or 
indexed. 


The software evaluates all subscripts in an INSPECT statement once, 
before the inspection begins; therefore, if the action of the INSPECT 
statement alters one of the subscripts, the new subscript value has no 
effect on the selection of operands during that inspection operation. 
For example, consider the following illustration: 


SS SS ee ee ee ee ee ee ol gl 
MOVE 1 TO TLY. | 
INSPECT FIELD1 TALLYING TLY 

| FOR ALL X(TLY). | 





Figure 3-49 
Sample Subscripted Argument 


In this sample statement, the software evaluates the address of X(TLY) 
only once, before it begins inspecting the field; hence, it will 
evaluate X(TLY) as X({1). The alteration of TLY by the action of 
inspecting and tallying has no effect on the choice of the X operand. 
(X(1) will be used throughout the operation.) 


NOTE 


When subscripting an INSPECT statement 
that contains both a TALLYING anda 
REPLACING phrase, keep in mind that the 
statement will be compiled into two 
separate INSPECT statements. Therefore, 
any field that is altered by the action 
of the INSPECT...TALLYING statement will 
be in its altered state if used as a 
subscript by the INSPECT...REPLACING 
statement. 


3.9.5 The TALLYING Phrase 


An INSPECT statement that contains a TALLYING phrase counts’ the 
occurrence of various character strings under certain stated 
conditions. It keeps the count in a user-designated field called, 
here, a tally counter. ; 
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3.9.5.1 The Tally Counter - The identifier that follows the word 
TALLYING designates the tally counter. The identifier may be 
subscripted or indexed. The data item must be a numeric integer with 
no editing or P characters; it may be COMP or DISPLAY usage, and it 
may be signed (separate or overpunched). 


Each time the tally argument matches the delimited string being 
inspected, the software adds 1 to the tally counter. 


The programmer can initialize the tally counter to any numeric value. 


3.9.5.2 The Tally Argument - The tally argument specifies a 
character-string and a condition under which that string should be 
compared to the delimited string being inspected. The following 
figure shows the format of the tally argument: 


ena 
literal 


Figure 3-50 
Format of the Tally Argument 






eet } 
LEADING 
CHARACTERS 





The CHARACTERS form of the tally argument specifies that every 
character in the delimited string being inspected should be considered 
to match an imaginary character that serves as the tally argument. 
This increments the tally counter by a value that equals the size of 
the delimited string. For example, the statement in the following 
illustration causes TLY to be incremented by the number of characters 
that precede the first comma, regardless of what those characters 
might be. 


INSPECT FIELD1 TALLYING TLY FOR 


CHARACTERS BEFORE ",". 





Figure 3-51 
CHARACTERS Form of the Tally Argument 


The ALL and LEADING forms of the tally argument specify a particular 
character string, which may be represented by either a literal or an 
identifier. The tally argument character string may be any length; 
however, each character of the argument must match a character in the 
delimited string before the software considers the argument matched. 


e A literal character string must be either non-numeric or a 
figurative constant (other than ALL literal). A figurative 
constant, such as SPACE, ZERO, etc., represents a_ single 
character and can be written as " ", or "OQ", etc., with the 
same effect. 


® An identifier must be'an elementary item of DISPLAY usage. 
It may be any data class. However, if it is other than 
alphanumeric, the software performs an implicit redefinition 
of the item. (This redefinition is identical to the 
BEFORE/AFTER delimiter redefinition discussed earlier in 


Section 3.9.1.) 
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The words ALL and LEADING supply conditions that further delimit the 
inspection operation. 


e The word ALL specifies that every match that the search 
argument finds in the delimited character string be counted 
in the tally counter. When a literal follows the word ALL, 
it does not have the same meaning as the figurative constant, 
ALL literal. (The ALL literal meaning of ALL "," is a string 
of consecutive commas, aS many as the context of the 
statement requires.) ALL "," used as a tally argument means, 
"count each comma without regard to adjacent characters." 


@ The word LEADING specifies that only adjacent matches of the 
TALLY argument at the left-hand end of the delimited 
character string be counted. At the first failure to match 
the tally argument, the software terminates counting and 
causes the argument to become inactive. Consider the 
examples in Figure 3-52. (The sample statement is an 
INSPECT...TALLYING statement, scanning FIELD1, tallying in 
TLY, and looking for the arguments and delimiters in the 
left-hand column. Assume that the program initializes TLY to 
0.) 


FeRE*O*e*P 
F**OR** 


PREQRAR AK 
FR*¥PO*eF APR EE 


LEADING "**" AFTER "Q", 
FREPOR AAP RE 


RP*exXPREQS 





Figure 3-52 
Results of Counting with the 
LEADING Condition 


3.9.5.3 The Tally Argument List - One INSPECT...TALLYING statement 
can contain more than one tally argument, and each argument can have a 
separate BEFORE/AFTER phrase and tally counter associated with it. 
These tally arguments with their associated tally counters and 
BEFORE/AFTER phrases form an argument list. The manner in which this 
list is processed affects the action of any given tally argument. 


The following sample statements show INSPECT statements with argument 
lists. The text following each one tells how that list will be 
processed. 


INSPECT FIELD1 TALLYING T FOR 
ALL uu j " 


AGE. a 7 
ALL "W : Ww . 





Figure 3-53 
Argument List Adding Into 
One Tally Counter 
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These three tally arguments have the same tally counter, T, and are 
active over the entire field being inspected. Thus, this statement 
adds the total number of commas, periods, and semicolons in FIELD1 to 
the initial value of T. 


INSPECT FIELD1 TALLYING 
Tl FOR ALL "," 


T2 FOR ALL "." 
T3° FOR ALE." 2"; 





Figure 3-54 
Argument List Adding Into 
Separate Tally Counters 


Each tally argument in this statement has its own tally counter, and 
is active over the entire field being inspected. Thus, the action of 
this statement is to add the total number of commas in FIELD1 to the 
initial value of Tl, the total number of periods to the initial value 
of T2, and the number of semicolons to T3. 


INSPECT FIELD1 TALLYING 
Tl FOR ALL "," AFTER "A" 


T2 FOR ALL "." BEFORE "B" 
T3 FOR ALL ";". 





Figure 3-55 
Argument List (with Delimiters) Adding 
into Separate Tally Counters 


Each tally argument in this statement has its own tally counter; the 
first two arguments have delimiter phrases, and the last one is active 
over the entire field being inspected. Thus, the first argument is 
initially inactive and becomes active only after the scanner 
encounters an A; the second argument begins the scan in the active 
state but becomes inactive after a B has been encountered; and the 
third argument is active during the entire scan of FIELD1. 


Figure 3-56 shows various values of FIELD] and the contents of the 
three tally counters after the scan. Assume that the counters are 
initialized to 0 before the INSPECT statement. 


CONTENTS OF TALLY COUNTERS AFTER SCAN 
FIELD1 





Figure 3-56 
Results of the Scan in Figure 3-55 


The BEFORE/AFTER phrase applies only to the argument that precedes it, 
and delimits the field for that argument only. Each BEFORE/AFTER 
Phrase causes a separate scan of the field to determine the limits of 
the field for its corresponding argument. 
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3.9.5.4 Interference in Tally Argument Lists - When several tally 
arguments contain one or more identical characters that are active at 
the same time, they may interfere with each other (i.e., when one of 
the arguments finds a match, the scanner is stepped past the matching 
character(s) which prevents those character(s) from being considered 
for any other match). 


The example in Figure 3-57 illustrates two identical tally arguments 
that do not interfere with each other since they are not active at the 
same time. (The first A in FIELD1 causes the first argument to become 
inactive and the second argument to become active.) 


MOVE 0 TO Tl T2. 
INSPECT FIELD1 TALLYING 


Tl FOR ALL "," BEFORE "A" 
T2 FOR ALL "," AFTER "A". 





Figure 3-57 
Two Tallying Arguments that 
Do Not Interfere with Each Other 


The two identical tally arguments in Figure 3-58 will interfere with 
each other since both are active at the same time. (For any given 
position of the scanner, the arguments are applied to FIELD] in the 
order in which they appear in the statement. When one of them finds a 
Match, the scanner moves to the next position and ignores’ the 
remaining arguments in the argument list.) Each comma in FIELD] causes 
Tl to be incremented by 1 and the second argument to be ignored. 
Thus, Tl will always contain an accurate count of all of the commas in 


FIELD1, and T2 will always be unchanged. 


| INSPECT FIELD1 TALLYING | 


Tl FOR ALL "," 
T2 FOR ALL "," AFTER "A". 





Figure 3-58 
Two Tallying Arguments that 
Do Interfere with Each Other 


The following statement achieves the same results as the statement in 
Figure 3-57. The first argument does not become active until the 
scanner encounters an A. The second argument tallies all commas’ that 
precede the A. After the A, the first argument counts all commas and 
causes the second argument to be ignored. Thus, Tl contains’ the 
number of commas that precede the first A and T2 contains the number 
of commas that follow the first A. This statement works well as 
written, but could be more confusing to debug than the one in Figure 
3=57 


INSPECT FIELD1 TALLYING 
T2 FOR ALL "," AFTER "A" 


id “FOR ALE, Ys 





Figure 3-59 
Two Tallying Arguments that, 
Because of their Positioning, 
Only Partially Interfere with 
Each Other 
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The preceding three examples show that one INSPECT statement cannot 
count any character more than once. Thus, when using the same 
character in more than one argument of an argument list, consider the 
nature of the interference and choose the order of the arguments very 
carefully. The solution to the problem may require two or more 
INSPECT statements. Consider the following problem: 


INSPECT FIELD1 TALLYING 


Tl FOR ALL "AB" 
T2 FOR ALL "BC". 





Figure 3-60 
An Attempt to Tally the Character B 
with Two Arguments 


If FIELD1 contains "ABCABC", after the scan Tl will be incremented by 
a 2 and T2 will be unaltered. The successful matching of the argument 
includes each B in the field. Each match resets the scanner to the 
character position to the right of the B, and causes the second 
argument to never be successfully matched. Reversing the order of the 
arguments has no effect, the results remain the same. Only separate 
INSPECT statements can develop the desired counts. 


Sometimes the programmer can use the interference characteristics of 
the INSPECT statement to good advantage. Consider the following 
sample argument list: 


MOVE 0 TO T4 T3 T2 Tl. 
INSPECT FIELD1 TALLYING 
FOR ALL. "**#**" 


FOR “ALL 742%" 
FOR ALL "#2" 
FOR ALL "*", 





Figure 3-61 
Tallying Asterisk Groupings 


The argument list in Figure 3-61 counts all of the asterisks in FIELD1 
but in four different tally counters. T4 counts the number of times 
that four asterisks occur together; T1T3 counts the number of times 
three asterisks appear together; T2 counts double asterisks; and Tl 
counts singles. 


If FIELD1 contains a string of more than four consecutive asterisks, 
the argument list breaks the string into groups of four, and counts 
them in T4. It then counts the less-than-four remainder in T3, T2, or 
Tl. 


es Tl to count 


Reversing the order of the arguments in this list caus 
to remain unchanged. 


all of the asterisks and T2, T3, and T4 
When the LEADING condition is used with an argument in the argument 
list, that argument becomes inactive as soon as it fails to be matched 
in the field being inspected. Therefore, when two arguments in an 
argument list contain one or more identical characters and one of the 
arguments has a LEADING condition, the argument with the LEADING 
condition should appear first. Consider the following sample 
statement: 
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| MOVE O TO Tl T2. | 
INSPECT FIELD1 TALLYING 


| Ti FOR LEADING "*" 
| £2 POR. AGL "5 | 


Figure 3-62 
Placing the LEADING Condition 
in the Argument List 


The placement of the LEADING condition in this sample statement causes 
Tl to count only leading asterisks in FIELD1; the occurrence of any 
other character stops this counting and causes the first tally 
argument to become inactive. TZ keeps a count of any remaining 
asterisks in FIELD1. 


Reversing the order of the arguments in this statement results in an 
argument list that can never increment Tl. 


| INSPECT FIELD1 TALLYING | 
T2 FOR ALL "*" 
| Tl FOR LEADING "*", | 


Figure 3-63 
Reversing the Argument 
List in Figure 3-62 





If the first character in FIELD1 is not an asterisk, neither argument 
can match it and the second argument becomes inactive. If the first 
character in FIELD1 is an asterisk, the first argument matches’ and 
causes the second argument to be ignored. The first non-asterisk 
character in FIELD1 will fail to match the first argument and _ the 
second argument will become inactive. (The second argument becomes 
inactive because it has not found a match in all of the preceding 
characters.) 


An argument with both a LEADING condition and a BEFORE phrase can 
sometimes sucessfully "delimit" the field being inspected: 


MOVE 0 TO Tl T2. 
INSPECT FIELD1 TALLYING 
Tl FOR LEADING SPACES 
T2 FOR ALL " " BEFORE "." 


T2 FOR ALL " " BEFORE "," 
T2 FOR ALL " " BEFORE ".". 
IF T2 > 0 ADD 1 TO T2. 





Figure 3-64 
An Argument List that Counts 
Words in a Statement 


The statements in Figure 3-64 count the number of "words" in the 
English statement in FIELDI. (This assumes that no more than three 
spaces separate the words in the sentence and that the sentence ends 
with a period.) When FIELD1 has been scanned, T2 contains the number 
of gaps between the words. Since a count of the gaps renders a number 
that is one less than the number of words, the conditional statement 
adds one to the count. 
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The first argument removes any leading spaces, counting them in a 
different tally counter. This shortens FIELD1 by preventing the 
application of the second through the fourth arguments until the 
scanner finds a non-space character. The BEFORE phrase on each of the 
other arguments causes them to become inactive when the scanner 
reaches the period at the end of the sentence. Thus, the BEFORE 
phrases "Shorten" FIELD] by making the second through the fourth 
arguments inactive before the scanner reaches the right-hand end of 
FIELD1. If the sentence in FIELD] is indented with tab characters 
instead of spaces, a second LEADING argument can count the tab 
characters. The following sample statement illustrates this 
technique: 


INSPECT FIELD1 TALLYING 
Tl FOR LEADING SPACES 


Tl FOR LEADING TAB 
T2 FOR ALL " "etc. 





Figure 3-65 
Counting Leading Tab or Space Characters 


When an argument list contains a CHARACTERS argument, it should be the 
last argument in the list. Since the CHARACTERS argument always 
matches the field, it prevents the application of any of the following 
arguments in the list. However, as the last argument in an argument 
list, it can count the remaining characters in the field being 
inspected. Consider the following illustration. 


MOVE 0 TO Tl T2 T3 T4 T5. 
INSPECT FIELD1 TALLYING 
Tl FOR LEADING SPACES 
FOR ALL "." BEFORE 


FOR ALL "+" BEFORE 
FOR ALL "-" BEFORE ", 
FOR CHARACTERS BEFORE ",". 





Figure 3-66 
Counting the Remaining Characters 
With the CHARACTERS Argument 


Tf FIELD] is known to contain a number in the form frequently used to 
input data, it may contain a plus or minus sign, and a decimal point; 
further, the number may possibly be preceded by spaces and terminated 
by a comma. If this statement were compiled and executed, it would 
deliver the following results: 

TL would contain the number of leading spaces, 

T2 would contain the number of periods, 

r3 would contain the number of plus signs, 


T4 would contain the number of minus signs, 


T5 would contain the number of remaining characters (assumed to 
be numeric), and 


the sum of Tl through T5 (plus 1) gives the character position 
occupied by the terminating comma. 
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3.9.6 The REPLACING Phrase 


When an INSPECT statement contains a REPLACING phrase, that statement 
selectively replaces characters or groups of characters in the 
designated field. 


The REPLACING phrase names a search argument consisting of a character 
string of one or more characters and a condition under which the 
string may be applied to the field being inspected. Associated with 
the search argument is the replacement value, which must be the same 
length as the search argument. Each time the search argument finds a 
match in the field being inspected, under the condition stated, the 
replacement value replaces the matched characters. 


A BEFORE/AFTER phrase may be used to delimit the area of the field 
being inspected. A search argument applies only to the delimited area 
of the field. 


3.9.6.1 The Search Argument - The search argument of the REPLACING 
phrase names a character string and a condition under which the 
character string should be compared to the delimited string being 


co 


inspected. Figure 3-67 shows the format of the search argument: 


identifier 
LEADING 


literal 





Figure 3-67 
Format of the Search Argument 


The CHARACTERS form of the search argument specifies that every 
character in the delimited string being inspected should be considered 
to match an imaginary character that serves as the search argument. 
Thus, the replacement value replaces each character in the delimited 
string. (The replacement value, in this case, must be one character 
long.) 


The ALL, LEADING, and FIRST forms of the search argument specify a 
particular character string, which may be represented by a literal or 
an identifier. The search argument character string may be any 
length. However, each character of the argument must match a 
character in the delimited string before the software considers’ the 
argument matched. 


e A literal character string must be either non-numeric or a 
figurative constant (other than ALL literal). A figurative 
constant, such as SPACE, ZERO, etc., represents a_ single 
character and can be written as " ", "0", etc. with the same 
effect. Since a figurative constant represents a single 
character, the replacement value must be one character long. 


e An identifier must represent an elementary item of DISPLAY 


usage. It may be any class. However, if it is other than 
alphabetic, the software performs an implicit redefinition of 
the item. (This redefinition is identical to the 
BEFORE/AFTER delimiter redefinition discussed in Section 
Sa els) 
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The words ALL, LEADING, and FIRST supply conditions which further 
delimit the inspection operation: 


e The word ALL specifies that each match that the _ search 
argument finds in the delimited string is to be replaced by 
the replacement value. When a literal follows the word ALL, 
it does not have the same meaning as the figurative constant, 
ALL literal. (The figurative constant meaning of ALL "," is 
a string of consecutive commas, aS many as the context of the 
statement requires.) ALL "," as a search argument of the 
REPLACING phrase means, "replace each comma without regard to 
adjacent characters." 


e The word LEADING specifies that only adjacent matches of the 
search argument at the left-hand end of the delimited 
character string be replaced. At the first failure to match 
the search argument, the software terminates the replacement 
operation and causes the argument to become inactive. 


© The word FIRST specifies that only the leftmost character 
string that matches the search argument is to be replaced. 
After the replacement operation, the search argument 
containing this condition becomes inactive. 


3.9.6.2 The Replacement Value - Whenever the search argument finds a 
match in the field being inspected, the matched characters are 
replaced by the replacement value. The word BY followed by an 
identifier or literal specifies the replacement value. 


identifier 
BY 


literal 





Figure 3-68 
Format of the Replacement Value 


The replacement value must always be the same size as its associated 
search argument. 


If the replacement value is a literal character string, it must be 
either a non-numeric literal or a figurative constant (other than ALL 
literal). A figurative constant represents as many characters as’ the 
length that the search argument requires. 


If the replacement value is an identifier, it must be an _ elementary 
item of DISPLAY usage. It may be any class. However, if it is other 
than alphanumeric, the software conducts an implicit redefinition of 
the item. (This redefinition is the same as the BEFORE/AFTER 
redefinition discussed in Section 3.9.1.) 


3.9.6.3 The Replacement Argument - The replacement argument consists 
of the search argument (with its condition and character string), the 
replacement value, and an optional BEFORE/AFTER phrase. 
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| ALL ";" BY SPACE BEFORE "." | 
Pe ae ae VA “A perore/aPrER | 


argument phrase (optional) 






replacement 
value 


Figure 3-69 
The Replacement Argument 


3.9.6.4 The Replacement Argument List - One INSPECT...REPLACING 
statement can contain more than one replacement argument. Several 
replacement arguments form an argument list, and the manner in which 
the list is processed affects the action of any given replacement 
argument. 


The following examples show INSPECT statements with replacement 
argument lists. The text following each one tells how that list will 
be processed. 


(eee ee” ee fen ees eee ee 
| INSPECT FIELD1 REPLACING | 


| ALL BY SPACE | 


f 
ALL "." BY SPACE 


| ALL ";" BY SPACE. | 


Figure 3-70 
Replacement Argument List that is 
Active Over the Entire Field 


These three replacement arguments all have the same replacement value, 
SPACE, and are active over the entire field being inspected. 


Thus, this statement replaces all commas, periods, and semicolons with 
Space characters; and leaves all other characters unchanged. 


INSPECT FIELD] REPLACING 
ALL iT 0 " BY " 1 W 


ALL "y uv BY uo" 





Figure 3-71 
Replacement Argument List that 
"Swaps" Ones for Zeroes and Zeroes for Ones 


Each of these two replacement arguments has its own replacement value, 
and is active over the entire field being inspected. This statement 
exchanges zeros for ones and ones for zeroes, and leaves all other 
characters unchanged. 


NOTE 


When a search argument finds a match in 
the field being inspected, the software 
replaces that character string and scans 
to the next position beyond the replaced 
characters. It ignores the remaining 
arguments and applies the first argument 
in the list to the character string in 
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the new position. Thus, it never 
inspects the new value that was supplied 
by the replacement operation. Because 
of this, the search arguments may have 
the Same values as the replacement 
arguments with no chance of 
interference. 


| INSPECT FIELD1 REPLACING | 
ALL "0" BY "1" BEFORE SPACE 


ALL "1" BY "0" BEFORE SPACE. 


Figure 3-72 
Replacement Argument List that 
Becomes Inactive with the 
Occurrence of a Space Character 


This sample statement is identical to the statement in Figure 3-71, 
except that, here, the first occurrence of a space character in FIELD1 
causes both arguments to become inactive. 


INSPECT FIELD1 REPLACING 
ALL "0" BY "1" BEFORE SPACE 


ALL "1" BY "0" BEFORE SPACE 
CHARACTERS BY "*" BEFORE SPACE. 





Figure 3-73 
Argument List with Three Arguments 
That Become Inactive with the 
Occurrence of a Space 


Just aS in the argument list in Figure 3-72, the first space character 
causes all of these replacement arguments to become inactive. This 
argument list exchanges zeroes for ones, ones for zeroes, and 
asterisks for all other characters that are in the delimited area. 


If the BEFORE phrase is removed from the third argument, that argument 
will remain active across all of FIELD1l. Within the area delimited by 
the first space character, the third argument replaces all characters 
except ones and zeroes with asterisks. Beyond this area, it replaces 
all characters (including the space that delimited FIELD1 for the 
first two arguments and any zeroes and ones) with asterisks. 


3.9.6.5 Interference in Replacement Argument Lists - When’ several 
search arguments that are active at the same time contain one or more 
identical characters, they may interfere with each other, and 
consequently have an effect on the replacement operation. This 
interference of one search argument with the matching of other’ search 
arguments is similar to the interference that occurs between tally 
arguments. 


The action of a search argument is never affected by the BEFORE/AFTER 
delimiters of other arguments, since the software scans for delimiter 
Matches before it scans for replacement operations. 


The action of a search argument is never affected by the characters 
any replacement value, since the scanner does not inspect the replac 
characters again during execution of the INSPECT statement. 
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Interference between search arguments, therefore, depends on the order 
of the arguments, the values of the arguments, and the active-inactive 
status of the arguments. (The discussion in Section 3.9.5.4 
Interference in Tally Argument Lists, applies, generally, to 
replacement arguments as well.) 


The following rules will help minimize interference in replacement 
argument lists: 


1. Place search arguments with LEADING or FIRST conditions at 
the start of the list; 


2. Place several arguments with the CHARACTERS condition at’ the 
end of the list; 


3. Consider, very carefully, the order of appearance of any 


search arguments that contain one or more identical 
characters. 


3.9.7 Common Errors, INSPECT Statement 
The most common errors made when writing INSPECT statements are: 
e Leaving the FOR out of an INSPECT...TALLYING statement. 


e Using the word "WITH" instead of "BY" in the REPLACING 
phrase. 


.@ Failing to initialize the tally counter. 
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NUMERIC CHARACTER HANDLING 


This chapter discusses numeric class data and the COBOL operations 
that can be performed on numeric data items. It is assumed that you 
have read Chapter 3, and that you understand the concept of COBOL data 
classes. 


4.1 USAGES 


The USAGE of a numeric class item specifies the form in which the data 
is stored in memory. PDP-11l COBOL has four formats for numeric data 
Storage: DISPLAY (which is equivalent to DISPLAY-6 and DISPLAY-7), 
COMPUTATIONAL (abbreviated COMP), COMPUTATIONAL-6 (abbreviated 
COMP-6), and COMPUTATIONAL-3 (abbreviated COMP-3). 


4.1.1 DISPLAY 


Items with DISPLAY usage are stored as strings of characters (bytes) 
in decimal radix with an assumed decimal point and optional sign. 


4.1.2 COMPUTATIONAL 


COMPUTATIONAL usage is the standard PDP-1ll binary format. A COMP item 
is stored as a binary value with an assumed decimal scaling position; 
it is automatically SYNCHRONIZED on a word boundary and stored in 
memory (in one, two, or four words) as follows: 


PICTURE RANGE STORAGE 

S$(9) to S9(4) l word (2 bytes) 
$9(5) to S9(9) 2 words (4 bytes) 
$9(1f) to S9(18) 4 words (8 bytes) 


Figure 4-1 indicates the significance of each byte in a COMP data item 
by the number in parentheses. For example, "(1)" indicates that the 
byte contains the lowest-valued bits. Observe that the computer 
address (the first-referenced byte) of each COBOL data item 
corresponds to the low byte of the least significant word. 
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The number in parentheses also indicates the order of characters if 
the data item is redefined as an alphanumeric item. Consider an 
example of a two-word COMP item: 


$1 COMP-ITEM PIC 9(9) USAGE IS COMP. 
$1 GROUP-ITEM REDEFINES COMP-ITEM. 
@3  CHARACTER-ITEM PIC X OCCURS 4 TIMES. 
The subscripts of CHARACTER-ITEM correspond to the numbers in 
parentheses in Figure 4-1. 


NOTE 


The internal formats of one-word COMP 
and COMP-6 data items are identical. 


addressed 
word 


high low 
byte byte 
(2) (1) 





one-word COMP data item 


addressed 
word 





two-word COMP data item 


addressed 
word 


high low high low high low 
byte byte byte byte byte byte 
(2) (1) (4) (3) (8) (7) 





four-word COMP data item 


Figure 4-1 
Memory Storage of COMP Data Items 
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4.1.3 COMPUTATIONAL-6 











NOTE 


COMP-6 is temporarily defined for 
compatibility with the COMP data type in 
PDP-11 COBOL releases prior to Version 
4.98. Its use is not recommended except 
for converting data files containing 
data items defined as COMP in earlier 
releases of PDP-11 COBOL. COMP-6 is not 
compatible with the standard binary data 
types. 


A COMP-6 item is stored as a binary value with an assumed decimal 
scaling position; it is automatically SYNCHRONIZED on a word boundary 
and stored in memory (in one, two, three, or four words) as follows: 


PICTURE RANGE STORAGE 

S(9) to §$9(4) l word (2 bytes) 
$9(5) to S9(9) 2 words (4 bytes) 
S9(1@) to S9(14) 3 words (6 bytes) 
$9(15) to S9(18) 4 words (8 bytes) 


Figure 4-2 indicates the significance of each byte in a COMP-6 data 
item by the number in parentheses. For example, "(1)" indicates that 
the byte contains the lowest-valued bits. Note that the computer 
address (the first-referenced byte) of each COBOL data item 


corresponds to the low byte of the most significant word. 


The number in parentheses does not indicate the order of characters if 
the data item is redefined as an alphanumeric item. Consider an 
example of a four-word COMP-6 item: 





G1 COMP-6-ITEM PIC 9(16) USAGE IS COMP-6. 
@1 GROUP-ITEM REDEFINES COMP-6-ITEM. 
#3 CHARACTER-ITEM PIC X OCCURS 8 TIMES. 


The occurrences of the subscripted data item CHARACTER-ITEM map _ into 
memory storage as follows: 


OCCURRENCE OF BYTE (N) IN 
CHARACTER-ITEM FIGURE 4-2 
1 (7) 

2 (8) 

3 (5) 

4 (6) 

5 (3) 

6 (4) 

E} (1) 

8 (2) 
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NOTE 


The internal formats of one-word COMP 
and COMP-6 data items are identical. 


addressed 
word 





one-word COMPUTATIONAL-6 data item 


addressed 
word 


high low high low 
byte byte byte byte 
(4) (3) (2) (1) 


two-word COMPUTATIONAL-6 data item 


addressed next next 
word word word 


high low high low high low 
byte byte byte byte byte byte 
(6) (5) (4) (3) (2) (1) 


three-word COMPUTATIONAL-6 data item 








addressed 
word 





four-word COMPUTATIONAL-6 data item 


Figure 4-2 
Memory Storage of COMP-6 Data Items 
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4.1.4 COMPUTATIONAL-3 


COMP-3 specifies packed-decimal data items. They are stored as_ two 
decimal digits per byte (byte-aligned) with an assumed decimal scaling 
position. The sign is contained in the rightmost half (four bits) of 
the rightmost byte. 


The maximum size of a COMP-3 item is 18 decimal digits, regardless of 
the decimal scaling position. In the following example, both NUM-1 
and NUM-2 represent COMP-3 items of maximum size: 


g3 NUM-1 PIC S9(18) USAGE IS COMP-3. 
93 NUM-2 PIC S9(6)V9(12) USAGE IS COMP-3. 


The description of a COMP-3 data item must have a sign in its PICTURE 
character-string. 


When you specify an even number of digits, the value zero is stored in 
the leftmost four bits of the leftmost byte. 


Signs resulting from operations in which the receiving item is 
specified as COMP-3 are: 


ny" binary 1199 octal 14 
—_" binary 1191 octal 15 


The following signs are also recognized as valid, but they are not 
generated as a result of program operations: 


Positive signs-— binary 1929, octal 12 
binary 119%, octal 14 
binary 111%, octal 16 
binary llll, octal 17 


Negative signs- binary 111, octal 13 
binary 1191, octal 15 


Figure 4-3 represents the memory storage of COMP-3 data items of one, 
two, and three digits: 





PICTURE S9 PICTURE S$9(2) PICTURE S9(3) 
value: +5 value: -32 value: +262 
Figure 4-3 


Memory Storage of COMP-3 Data Items 
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4.2 DECIMAL SCALING POSITION 


The assumed decimal scaling position, or scaling factor, is not stored 
aS part of an actual numeric value. However, it is used by the OTS to 
control operations on numeric data items. Consider the following 
field description: 


1 ORDER-PRICE PIC 99V99 COMP VALUE 12.34. 


PDP-11 COBOL stores this item as a l-word. binary number. The word 
contains the integer vaiue 1234 and another location contains the 
scaling factor. In this example, the scaling factor records the fact 
that this integer has two decimal fractional positions. Thus, the 
COBOL OTS knows that the stored binary integer is 1f@ times larger 
than the programmer intends it to be. 


If the compiler encounters the following statement: 
ADD 1 TO ORDER-PRICE. 


it generates instructions to add a 1 to the 1234 in ORDER-PRICE. The 
OTS, however, scales the literal 1 up by two decimal places and adds 
the resultant literal, 19%, to the number in ORDER-PRICE. Thus, after 
the ADD operation, ORDER-PRICE contains the new value 1334 (which is 
actually 13.34 with the stored decimal scaling position). 


Thus, the PDP-11 COBOL compiler and OTS manipulate the data in 
DISPLAY, COMP, COMP-6, and COMP-3 data items in much the Same way. 
All four usages have exactly the same accuracy and precision, and can 
be freely mixed in a _ program. To illustrate, if a DISPLAY usage 
number and a COMP usage number are both involved in the same 
arithmetic statement, the OTS converts them to a common radix with no 
loss of information. It also converts the result, if necessary, with 
no loss of significance. 


The only effect of specifying a binary or packed-decimal usage is that 
it reduces the space required for most numbers and can speed up the 
execution of arithmetic statements. 


4.3 SIGN CONVENTIONS 


COMP-3 data items must be signed; however, DISPLAY, COMP, and COMP-6 
numeric items can be signed or unsigned. Unsigned numbers can contain 
values that range from zero to the largest positive value allowed by 
their declared precision. Negative values are not allowed. All 
PDP-11 COBOL arithmetic operations yield signed results. When the OTS 
must store such a result, whether positive or negative, in an unsigned 
data item, it stores only the absolute value of the result. Thus, 
unsigned items always contain zero or positive values. 


This guide does not recommend unsigned numbers for general use. They 
are uSually a source of programming errors, and are handied less 
efficiently than signed quantities by the OTS. 


Signed quantities always contain a numeric value and an _ operational 
sign. The OTS stores the sign with the numeric value in a variety of 
ways depending on the usage of the item and the presence of the SIGN 
clause. 
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NOTE 


If numeric data is read into a field 
described using the picture character S, 
then that data must include an 
operational sign of the appropriate 
format to pass the NUMERIC test. 


PDP-I1 COBOL always stores signed COMP and COMP-6 items in two's 
complement binary form. Thus, the high-order bit indicates the sign 
of the item. Sign representation for COMP-3 data items is described 
in Section 4.1.4. 


PDP-11 COBOL always stores signed DISPLAY items as a sequence of byte 
positions containing numeric ASCII characters. It may include the 
Sign in the high-order byte, the low-order byte, or as a_ separate, 
extra, byte on either the high-order or low-order end of the item. 


When the OTS stores the sign as part of a byte that also contains a 
numeric digit, the sign causes a value change in that byte and, hence, 
changes the value of the numeric digit. Table 4-1 shows the actual 


ASCII character that results when a numeric value and a sign share the 
same byte. 


Table 4-1 
The Resulting ASCII Character From a 
Sign and Digit Sharing the Same Byte 





| | | DIGIT VALUE 





A byte containing a +f@ stores as an octal 173, which prints as either 
a { or a [| depending on the printing device. 


A byte containing a -f# stores as an octal 175, which prints as_ either 
a } or a ] depending on the printing device. 


When the OTS stores the sign as a separate distinct character, the 
actual ASCII character that it stores is the graphic plus sign (octal 
953) or the graphic minus sign (octal 955). 
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4.4 ILLEGAL VALUES IN NUMERIC FIELDS 

All PDP-11 COBOL arithmetic operations store legal values in their 
result fields. However, it is possible, by reading invalid data or 
through redefinition and group moves, to store data in numeric fields 
that do not obey the descriptions of those fields. (For example, it 
is possible to place signed values into unsigned fields, and to place 
non-numeric or improperly signed data into signed numeric DISPLAY 
fields.) 


The results of arithmetic operations that use invalid data in numeric 
fields are unpredictable. 


4.5 TESTING NUMERIC FIELDS 


COBOL provides the following three kinds of tests for evaluating 
numeric fields: 


1. Relation tests, that compare the field's contents to another 
numeric value; 


2. Sign tests, that examine the field's sign to see if it is 
positive or negative; and, 


3. Class tests, that inspect the field's digit positions for 
legal numeric values. 


The following sub-sections explain these tests in detail. 


4.5.1 Relation Tests 


A relation test compares two numeric quantities and determines if the 
specified relation between them is true. For example, the following 
statement compares FIELD] to FIELD2 and determines if the numeric 
value of FIELD] is greater than the numeric value of FIELD2. If so, 
the relation condition is true and program control takes the True path 
of the statement. 


TF UPIBLDI. > FIELD2: :s:«« 
Either field in a relation test may be a numeric iteral or the 
figurative constant, ZERO. (The numeric literals @, $@, 8.8, or ZERO 
are all equivalent, both in meaning and in execution speed.) 


The sizes of the fields in a numeric relation test do not have to be 
the same (this includes the sizes of numeric literals). The 
comparison operation aligns both fields on their assumed decimal 
positions (through actual scaling operations in temporary locations or 
by accessing the individual digits) and supplies leading or trailing 
{as required) zeroes to either or both fields. 


The comparison operation always compares the signs of non-zero fields 
and considers positive fields to be greater than negative fields. 
However, since it does not compare them, positive zeroes and negative 
zeroes are equal. (A negative zero could arrive in a field through 
redefinition of the field or a MOVE to a group item.) Further, the 
Operation considers unsigned numeric fields to be positive. 
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The form of representation of the number (COMP, COMP-6, COMP-3, or 
DISPLAY usage) and the various methods of storing DISPLAY usage signs 
have no effect on numeric relation tests. 


For comparison purposes, the operation converts any illegal characters 


stored in DISPLAY usage fields to zeroes. It does not, however, alter 
the actual values in those fields. 


4.5.2 Sign Tests 


The sign test compares a numeric quantity to zero and determines if it 
is greater (positive), less (negative), or equal (zero). Both the 
relation test and the sign test can perform this’ function. For 
example, consider the following relation test: 


IF FIELD] > @ ... 
Now consider the following sign test: 

IF FIELD1 POSITIVE ... 
Both of these tests accomplish the same thing and would always arrive 
at the same resuit. The sign test, however, shortens the statement 
and shows, at a glance, that it is testing the sign. 
Table 4-2 shows the sign tests and their equivalent relation tests as 


applied to FIELD1. 


Table 4-2 
The Sign Tests 


SIGN TEST EQUIVALENT RELATION TEST 


FIELD1 POSITIVE ... FIELD1 
FIELD1 NOT POSITIVE FIELD1 
FIELD1 NEGATIVE ... FIELD1 
_FIELD1 NOT NEGATIVE FIELD1 
FIELD1 ZERO ... FIELD1 
FIELD1 NOT ZERO ... FIELD1 





Sign tests have no execution speed advantage over relation tests. The 
compiler actually substitutes the equivalent relation test for every 
correctly written sign test. (Sections 4.2.1 and 4.2.2 discuss the 
acceptable sign values and the treatment of illegal sign values.) 
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4.5.3 Class Tests 


The class test interrogates a numeric field to determine if it 
contains numeric or alphabetic data, and uses the result to alter the 
flow of control in a program. For example, the following statement 
determines if FIELD] contains numeric data. If so, the test condition 
is true and program control takes the true path of the statement. 


IF FIELD1 IS NUMERIC ... 


When reading in newly prepared data, it is often desirable to check 
certain fields for valid values. Relation tests and sign tests can 
only determine if the field's contents are within a certain range, and 
these tests both treat illegal characters in DISPLAY usage items as 
zeroes. Thus, some data preparation errors could pass both of these 
tests. 


The NUMERIC class test checks numeric (or alphanumeric) DISPLAY usage 
fields for valid numeric digits. 


If the field being tested contains a sign (whether carried as an 
overpunch or as a separate character), the test checks it for a valid 
sign value. If the character position carrying the sign contains an 
illegal sign value, the NUMERIC class test rejects the item and 
program control takes the false path of the IF statement. If the 
character position contains a valid sign and all digit positions in 
the field contain valid numeric digits, the NUMERIC class test passes 
the item and program control takes the true path of the IF statement. 


The ALPHABETIC class test checks alphabetic (or alphanumeric) fields 
for valid alphabetic characters and the space character. If all of 
the character positions of the field contain ASCII characters (A-Z or 
Space), the item passes the ALPHABETIC class test and causes program 
control to take the true path of the IF statement. (For further 
information concerning the ALPHABETIC class test, see Chapter 3, 
Section 3.3.2.) 


4.6 THE MOVE STATEMENT 
The MOVE statement moves the contents of one field into another. The 
following sample MOVE statement moves the contents of FIELD1 into 
FIELD2. 
MOVE FIELD1 TO FIELD2. 

Section 3.5 discusses the basic MOVE statement. This section 
considers MOVE statements as applied to numeric fields. These MOVE 
statements can be grouped into the following three categories: 

i. Group moves, 

2. Elementary moves with numeric receiving fields, and 


3. Elementary moves with numeric edited receiving fields. 


The following three sub-sections (4.6.1, 4.6.2, and 4.6.3) discuss 
each of these categories separately. 
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4.6.1 Group Moves 


The software considers a move to be a group move if either the sending 
field or the receiving field is a group item. It treats both fields 
in a group move as alphanumeric class fields and performs the move as 
an alphanumeric to alphanumeric elementary move. 


If either field in a group move is a numeric elementary item, the OTS 
treats the storage area occupied by that item as a field of 
alphanumeric bytes; thus, it ignores the USAGE, sign, and decimal 
point location characteristics of the numeric item. 


Only the item's allocated size, in bytes, affects the move operation. 
The OTS considers a separate sign character to be part of the item and 
moves it with the numeric digit positions. 


4.6.2 Elementary Numeric Moves 


If both fields of a MOVE statement are elementary items and _ the 
receiving field is numeric, the OTS considers the move to be an 
elementary numeric move. (The sending field may be either numeric or 
alphanumeric.) Tne numeric receiving fieid may be DISPLAY, COMP, 
COMP-6, or COMP-3 usage. The elementary numeric move converts’ the 
data format of the sending field to the data format of the receiving 
field. 


An alphanumeric sending field may be either an elementary data item or 
any alphanumeric literal other than the figurative constants SPACE, 
QUOTE, LOW-VALUE, HIGH-VALUE, or ALL "literal". The elementary 
numeric move accepts the figurative constant ZERO and considers it to 
be equivalent to the numeric literal @. It treats alphanumeric 
sending fields as unsigned integers of DISPLAY usage. 


If necessary, the numeric move operation converts the sending field to 
the data format of the receiving field and aligns the sending field's 
decimal point on that of the receiving field. It then moves’ the 
sending field digits to their corresponding receiving field digits. 


If the sending field has more digit positions than the receiving 
field, the decimal point alignment operation truncates the sending 
field, with the resultant loss of digits. The end truncated 
(high-order or low-order) depends upon the number of sending field 
digit positions that find matches on each side of the receiving 
field's decimal point. If the receiving field has fewer digit 
positions on both sides of the decimal point, the operation truncates 
both ends of the sending field. Thus, if a field described as PIC 
999V999 is moved to a field described as PIC 99V99, it loses one digit 
from the left end and one from the right end. Figure 4-4 illustrates 
this alignment operation (the carat (*~ ) indicates the stored decimal 
scaling position): 
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fl AMOUNT1 PIC 99V99. 


MOVE 123.321 TO AMOUNTI. 





Figure 4-4 
Truncation Caused By Decimal Point Alignment 


If the sending field has fewer digit positions than the receiving 
field, the move operation supplies zeroes for all unfilled digit 
positions. Figure 4-5 illustrates this alignment (the carat ( ) 
indicates the stored decimal scaling position): 


f1 TOTAL-AMT PIC 999V99. 


MOVE 1 TO TOTAL-AMT. 


Before execution Goo Oe 





After execution $01 9 


Figure 4-5 
zero Filling Caused By Decimal Point Alignment 
The following statement produces the same results: 
MOVE $91.68 TO TOTAL-AMT. 


Consider the following two MOVE statements and their resultant 
truncating and zero-filling effects: ; 


STATEMENT TOTAL-AMT AFTER EXECUTION 
MOVE $19 TO TOTAL-AMT 198 go 
MOVE "99199" TO TOTAL-AMT 1gg oo 


Literals with leading or trailing zeroes have no significant advantage 
in space or execution speed with PDP-11 COBOL, and the zeroes are 


often lost by decimal point alignment. 


The MOVE statement's receiving fie dictates how the sign will be 
moved. A signed DISPLAY uSage receiving field causes the sign to be 
moved as a separate guantity. An unsigned DISPLAY usage receiving 
field causes no sign movement. A COMP or COMP-6 uSage receiving 
field, whether signed or unsigned, cauSes the sign to be moved; 
however, if the receiving field is unsigned, the OTS sets its value to 
absolute. A COMP-3 receiving field always causes the sign to be 
moved. 
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4.6.3 Elementary Numeric Edited Moves 


The PDP-11 COBOL object time system considers an elementary numeric 
move to a receiving field of the numeric edited category to be an 
elementary numeric edited move. The sending field of an elementary 
numeric edited move may be either numeric or alphanumeric and, if 
numeric, its usage can be DISPLAY, COMP, COMP-6, or COMP-3. The OTS 
treats alphanumeric sending fields in numeric edited moves as unsigned 
DISPLAY usage integers. 


The OTS considers the receiving field to be numeric edited category if 
it is described with a BLANK WHEN ZERO clause, or a combination of the 
following symbols: 


B Space insertion position; 

P Decimal scaling position; 

V Location of assumed decimal point; 

Z Leading numeric character position to be replaced by a space 


if the position contains a zero; 


g zero insertion position; 

9 Position contains a numeric character; 

/ Slash insertion position; 

; Comma insertion position; 

- Decimal point insertion position; 

- Leading numeric character position to be replaced by an 


asterisk if the position contains a zero; 
+ Positive editing sign control symbol; 
= Negative editing sign control symbol; 
CR Credit editing sign control symbol; 
DB Debit editing sign control symbol; 
cs Currency symbol ($) insertion position. 


A numeric edited field may contain 9, V, and P, but combinations_ of 
those symbols without an editing character do not make the field 
numeric edited. 


The numeric edited move operation first converts the sending field to 
DISPLAY usage and aligns both fields on their decimal point locations, 
truncating or padding (with zeroes) the sending field until it 
contains the same number of digit positions on both sides of the 
decimal point as the receiving field. It then moves the resulting 
digit values to the receiving field digit positions following the 
COBOL editing rules. 
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The COBOL editing rules allow the numeric edited move operation to 
perform any of the following editing functions: 


@ Suppress leading zeroes with either spaces or asterisks; 

@e Float a currency sign and a plus or minus sign through 
Suppressed zeroes, inserting the sign at either end of the 
field; 

e Insert zeroes and spaces; 


@ Insert commas and a decimal point. 


Figure 4-6 illustrates several of these functions with the statement, 
MOVE FLD-B TO TOTAL-~AMT. (Assume that FLD-B is described as 


S9999V99.) 
TOTAL-AMT 
PICTURE STRING CONTENTS AFTER MOVE 


2222.99 23.69 
+4+4+4+.99 ~85.96 
2,222.99 1,234.99 
$,$$$.99 $12.34 


$,$$9.99 $9.34 
$$,$$$.99 $1,234.99 
$$9,999.99 $8,812.34 
$$$$,$$$.99 $12.34 
$$$,$S$.$$ 
++4++.99 -12.34 
S*¥e* EEK _ QQ S*¥**EE]1 2,34 





Figure 4-6 
Numeric Editing 


The currency symbol (S$) and the editing sign control symbols (+ -) are 
the only floating symbols. To float them, enter a string of two or 
more occurrences of the symbol. 


4.6.4 Common Errors, Numeric MOVE Statements 


The most common errors made when writing numeric MOVE statements are: 


@e Placing an incorrect number of replacement characters in a 
numeric edited item. 

@e Moving non-numeric data into numeric fields with group moves. 

e Trying to float the $ or + insertion characters past the 
decimal point to force zero values to appear as .@@f instead of 
Spaces. (Use $$.99 or ++.99.) 

@e Forgetting that the $ or + insertion characters require an 
additional position on the ieftmost end that cannot be 
replaced by a digit (unlike the * insertion character which 
can be completely replaced). 
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4.7 THE ARITHMETIC STATEMENTS 


The COBOL arithmetic statements, ADD, SUBTRACT, MULTIPLY, DIVIDE, and 
COMPUTE allow COBOL programs to perform simple arithmetic operations 
on numeric data. 


This section covers the use of COBOL arithmetic statements. The first 
five sub-sections (4.7.1 through 4.7.5) discuss the statements' common 
features, and the following five (4.7.6 through 4.7.18) discuss each 
statement individually. 


4.7.1 Intermediate Results 


Most forms of the arithmetic statements perform their operations in 
temporary work locations, then move the results to the receiving 
fields, aligning the decimal points and truncating or zero filling the 
resultant values. 


This temporary work field, called the intermediate result field, has a 


max imum size of 18 numeric digits. The actual size of the 
intermediate result field varies for each statement, and is determined 
at compile time based on the sizes of the cperands used by the 


Statement. 


When the compiler determines that the size of the intermediate result 
field exceeds 18 digits, it truncates the excess high-order digits. 
Thus, a program that requests a multiplication operation between the 
following two fields, 

PLC) 9128). and PIC: V¥99 


s + v . 


(which would otherwise cause the compiler to set up a 2@-digit 
intermediate result field -- 9(18)V99) actually causes the following 
intermediate result field 


PIC 9(16)V99. 


PDP-11 COBOL truncates high-order digits or low-order digits to the 
right of the decimal point, based on the assumption that most large 
data declarations are larger than ever need be, so zeroes occupy most 
of their high-order digit positions. Numeric data may be declared as 
PIC 9(12) or PIC 9(15) but the values that are placed in these fields 
will probably not exceed nine digits of range (1 billion) in most 
applications. 


When using large numbers (or numbers with many decimal places) that 
are close to 18 digits long, examine all of the arithmetic operations 
that manipulate those numbers to determine if truncation will occur. 


If truncation is a possibility, reduce the size of the number by 
dividing it by a power of 1 prior to the arithmetic operation. (This 
scaling down operation causes the low-order end to lose digits, but 
these are probably less critical.) Then, after the arithmetic 
Operation, multiply the result by the same power of 19. 


To save the low-order digits in such an operation, move the field to a 
temporary location before the scaling DIVIDE, perform separate, 
identical arithmetic operations on both the original and the temporary 
fields, then, after the scaling MULTIPLY, combine their results. 
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4.7.2 The ROUNDED Phrase 


Rounding-off is an important tool with most arithmetic operations. 
The ROUNDED phrase causes the OTS to round-off the results of COBOL 
arithmetic operations. 


The phrase may be used on any COBOL arithmetic statement. 
Rounding-off takes place only when the ROUNDED phrase requests it, and 
then only if the intermediate result has more low-order digits than 
the result field. 


PDP-11 COBOL rounds-off by adding a 5 to the leftmost truncated digit 
of the absolute value of the intermediate result before it stores that 
result. 


Consider the following illustration and assume an intermediate result 
of 54321.2468: 


G1 FLD-A PIC S9(5)V9999. 
gl FLD-B PIC S9(5)V99. 


ADD FLD-A TO FLD-B ROUNDED. 


Intermediate result field: 


PIC S9(6)V9999. 
| The ROUNDED operation: 


Intermediate result field: 954321.24 68, 
LEFT-MOST 


ROUNDED: (ADD) 68 |58 truncated 
FLD-B's ROUNDED result: 954321.25 {18 digit 





Figure 4-7 
Rounding Truncated Decimal Point Positions 


The following ROUNDING example rounds-off to the decimal scaling 
position (P). Assume an intermediate result of 2468M. (Section 4.5.4 
discusses the GIVING phrase in numeric operations.) 


G1 


AMOUNTI PIC 9999. 
@1 AMOUNT2 PIC 9999PP. 


| MULTIPLY AMOUNT] BY 19 | 
| | 


GIVING AMOUNT2 ROUNDED. 


ak a ee) 


Figure 4-8 
Rounding Truncated Decimal Scaling Positions 
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| Intermediate result field: | | 


i 


PIC 999999. 


The ROUNDED operation: 


Intermediate result field: 9246 
ROUNDED (ADD) : 


AMOUNT2's ROUNDED result: £247 





Figure 4-8 (continued) 
Rounding Truncated Decimal Scaling Positions 





The SIZE ERROR phrase detects the loss of high-order non-zero digits 
in the results of COBOL arithmetic operations. 


The phrase may be used on any COBOL arithmetic statement. 


When the execution of a statement with no SIZE ERROR phrase results in 
a size error, the OTS truncates the high-order digits and stores the 
result without notifying the user. When the execution of a statement 
with a SIZE ERROR phrase results in a size error, the OTS discards the 
entire result (it does not alter the receiving fields in any way) and 
executes the SIZE-ERROR imperative phrase. 


If the statement contains both ROUNDED and SIZE ERROR phrases, the OTS 
rounds the result before it checks for a size error. 


The phrase cannot be used on numeric MOVE statements. Thus, if a 
program moves a numeric quantity to a smaller numeric field, it may 
inadvertently lose high-order digits. For examplé, consider’ the 
following MOVE of a field to a smaller field: .* 


gl AMOUNT-A PIC 9(8)V99. 


g1 AMOUNT-B PIC 9(4)V99. 


MOVE AMOUNT-A TO AMOUNT-B. 


This MOVE operation always loses four of AMOUNT-A's high-order digits. 
Either of the following two statements could determine whether these 
digits are zero or non-zero, and could be tailored to any size field: 


1. IF AMOUNT-A NOT > 9999.99 
MOVE AMOUNT-A TO AMOUNT-B 
ELSE ... 


2. ADD ZERO TO AMOUNT-A GIVING AMOUNT-B 
ON SIZE ERROR ... 
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Both of these alternatives allow the MOVE operation to occur only if 
AMOUNT-A loses no significant digits. If the value in AMOUNT-A is too 
large, both alternatives avoid altering AMOUNT-B and take the 
alternative execution path. 


4.7.4 The GIVING Phrase 


The GIVING phrase moves the intermediate result field of an arithmetic 
Operation to a receiving field. (The phrase acts exactly like a MOVE 
statement with the intermediate result serving as a sending field and 
the data item following the word GIVING (in the statement) serving as 
a receiving field.) 


The phrase may be used on the ADD, SUBTRACT, MULTIPLY, and DIVIDE 
statements. 


If the data item following the word GIVING is a numeric edited field, 
the OTS performs the editing the same way it does for MOVE statements. 


4.7.5 Multiple Operands in ADD and SUBTRACT Statements 
Both the ADD and SUBTRACT statements may contain a String of more than 
one operand preceding the word TO, FROM, or GIVING. 


Multiple operands in either of these statements cause the OTS to _ add 
the string of operands together and use the intermediate result of 
that operation as a single operand to be added to or subtracted from, 
the receiving field. 


The following three equivalent coding groups illustrate how the 
software executes the multiple operand statements: 


1. Statement: ADDABCDTOEF GH. 


Equivalent coding: ADD A B, GIVING TEMP. 
ADD TEMP, C, GIVING TEMP. 
ADD TEMP, D, GIVING TEMP. 
ADD TEMP, E, GIVING E. 
ADD TEMP, F GIVING F. 
ADD TEMP, G GIVING G. 
ADD TEMP, H GIVING H. 


2. Statement: SUBTRACT A, B, C, FROM D. 
Equivalent coding: ADD A, B, GIVING TEMP. 
ADD TEMP, C GIVING TEMP. 
SUBTRACT TEMP FROM D GIVING D. 
3. Statement: ADD A BC D GIVING E. 
Equivalent coding: ADD A B GIVING TEMP. 


ADD TEMP C GIVING TEMP. 
ADD TEMP D GIVING E. 
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(Just as with all COBOL statements, any commas in these statements are 
optional.) 


Only statement 3 may have a numeric edited receiving field, since it 
is the only statement containing a GIVING phrase. 


4.7.6 The ADD Statement 


The ADD statement adds two or more operands together and stores’ the 
result. 


The statement may contain multiple operands (with the exception of 
Format 3) and the ROUNDED and SIZE ERROR phrases. It may be written 
in one of the following formats: 


Format 1. ADD FIELD] ...TO FIELD2 FIELD3 ... .« 
Format 2. ADD FIELD] FIELD2 ...GIVING FIELD3 FIELD4 ... . 
Format 3. ADD CORRESPONDING FIELDI1 TO FIELD2. 


In Format 1, the receiving fields (FIELD2, FIELD3) are one of the 
addends. These must not be in the numeric edited category. 


In Format 2, the receiving fields (FIELD3, FIELD4) are not one of the 
addends. They may either be numeric or numeric edited. When using 
this format, omit the word TO. 


In Format 3, the receiving field (FIELD2) is one of the addends. Both 
FIELD1 and FIELD2 must be group items. The corresponding elements of 
FIELD] are added to the corresponding elements of FIELD2. 


4.7.7 The SUBTRACT Statement 


The SUBTRACT statement subtracts one, or the sum of two or more, 
operands from another operand and stores the result. 


The statement may contain multiple operands (with the exception of 
Format 3) and the ROUNDED and SIZE ERROR phrases. It may be written 
in one of the following formats: 


Format 1. SUBTRACT FIELD] ... FROM FIELD2 FIELD3 ... . 


Format 2. SUBTRACT FIELD1 ... FROM FIELD2 
GIVING FIELD3 FIELD4 ... . 


Format 3. SUBTRACT CORRESPONDING FIELD1 FROM FIELD2. 


In Format 1, the receiving fields (FIELD2, FIELD3) are both the 
Subtrahend and the difference (the result). These must not be in the 
numeric edited category. 


In Format 2, the receiving fields (FIELD3, FIELD4) are used only to 
store the result. They may be either numeric or numeric edited. 


In Format 3, the receiving field (FIELD2) is both the subtrahend and 
the difference (results). Both FIELD] and FIELD2 must be group items. 
The corresponding elements of FIELD2. 
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4.7.8 The MULTIPLY Statement 


The MULTIPLY statement multiplies one operand by another and_ stores 
the result. 


The statement may contain the ROUNDED and SIZE ERROR phrases. It may 
contain multiple receiving operands. It may be written in either of 
the following formats: 


Format 1. MULTIPLY FIELD1 BY FIELD2, FIELD3 ... . 
Format 2. MULTIPLY FIELD1 BY FIELD2 GIVING FIELD3, FIELD4 ... . 


In Format 1, the receiving fields (FIELD2, FIELD3) are also. the 
multipliers. These must not be in the numeric edited category. 


In Format 2, the receiving fields (FIELD3, FIELD4) are neither 
multiplier nor multiplicand. These may be either numeric or numeric 
edited. 


COBOL's "near English" format could cause a problem with the MULTIPLY 
statement, since it is common to speak of multiplying a number 
(multiplicand) by another number (multiplier) and to think of the 
result as a new value for the multiplicand; thus: 


MULTIPLY EARNINGS BY 9.24. 
Multiplier 
Multiplicand 


This statement is incorrect since the OTS stores the result in the 
multiplier field, and this multiplier is a literal. The compiler 
could diagnose this error, but would not diagnose it if the multiplier 
were a data item. Consider this multiplier written as a data item: 


MULTIPLY EARNINGS BY TAX-RATE. 
The compiler would not diagnose this statement's error, and would 
store the result of the operation in TAX-RATE. A good practice when 
using MULTIPLY statements is to always write them in Format 2. This 
ensures that the result is properly stored. The following two 
statements safely capture their results: 


MULTIPLY EARNINGS BY §.24 GIVING EARNINGS. 
or 


MULTIPLY EARNINGS BY TAX-RATE GIVING EARNINGS. 


i> 
d 

bo 

(an) 
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4.7.9 The DIVIDE Statement 


The DIVIDE statement divides one operand into another and stores’ the 
result. 


The statement may contain the ROUNDED and SIZE ERROR phrases. With 
the exception of Formats 4 and 5, it may not contain multiple 
receiving operands. It may be written in any of the following 
formats: 


Format l. DIVIDE FIELD1 INTO FIELD2 FIELD3 ... . 

Format 2. DIVIDE FIELD1 INTO FIELD2 GIVING FIELD3 FIELD4 ... 

Format 3. DIVIDE FIELD2 BY FIELD1 GIVING FIELD3 FIELD4 ... . 

Format 4. DIVIDE FIELD] INTO FIELD2 GIVING FIELD3 REMAINDER 
FIELD4. 

Format 5. ees FIELD1 BY FIELD2 GIVING FIELD3 REMAINDER 
TIELD4. 


In Format 1, the receiving fields (FIELD2, FIELD3) are also the 
dividends. These must not be in the numeric edited category. 


In Formats 2 and 3, the receiving fields (FIELD3, FIELD4 ... ) are 
neither dividends nor divisor. These may be either numeric or numeric 
edited. 


In Formats 4 and 5, the receiving field (FIELD3) is neither a dividend 


nor adivisor. FIELD4 is the remainder. The receiving field and the 
remainder may be either numeric or numeric edited. 


4.7.18 The COMPUTE Statement 


The COMPUTE statement computes the value of an arithmetic expression 
and stores the value in the result. 


The statement may contain the ROUNDED and SIZE ERROR phrases. It may 
contain multiple receiving operands. The COMPUTE statement has the 
following format: 

COMPUTE FIELD1 FIELD2 ... = arithmetic-expression. 


The receiving fields (FIELD1, FIELD2) may be either numeric or numeric 
edited. 


4.7.11 Common Errors, Arithmetic Statements 
The most common errors made when using arithmetic statements are: 


e Using an alphanumeric class field in an arithmetic statement. 
The MOVE statement allows data movement between alphanumeric 
class fields and certain numeric class fields, but arithmetic 
statements require that all fields be numeric. 
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e Writing the ADD or SUBTRACT statements without the GIVING 
phrase, but attempting to put the result into a numeric 
edited field. 


e Writing a Format 2 ADD statement with the word TO; For 
example: 


ADD A TO B GIVING C. 


e Subtracting a 1 from a numeric counter that was described as 
an unsigned quantity, and testing for a valiue of less than 
zero. 


e Forgetting that the MULTIPLY statement, without the GIVING 
phrase, stores the result back into the second operand 
(multiplier). 


e Performing a series of calculations in such a way as_ to 
generate an intermediate result that is larger than 18 digits 
when the final result will be fewer digits. (The programmer 
should be careful to intersperse divisions with 
multiplications or to drop non-significant digits that result 
from multiplying large numbers (or numbers with many decimal 
places). 


e Performing an operation on a field that contains a value 
greater than the precision of its data description. This can 
happen only if the field was disarranged by a group move or 
redefinition. 


© Forgetting that, in an arithmetic statment containing 
multiple receiving fields, the ROUNDED phrase must be 
specified for each receiving field that is to be rounded. 


e Forgetting that, in an arithmetic statement containing 
multiple receiving fields, the ON SIZE ERROR phrase, if 
specified, applies to all receiving fields. Only those 
receiving operands for which a size error condition is raised 
are left unaltered. The ON SIZE ERROR imperative statement 
is executed after all the receiving fields are processed by 
the OTS. 


- 7 Sesame a eas OO eT kt 


4.8 ARITHMETIC EXPRESSION PROCESSING 


COBOL provides language facilities for manipulating user-defined data 
arithmetically. In particular, the language provides the arithmetic 
Statements ADD, SUBTRACT, MULTIPLY, and DIVIDE and the facilities of 
arithmetic expressions using the +, -, *, /, and ** operators. In 
simple terms, a given arithmetic functionality may be expressed in one 
of several ways. For example, consider a COBOL application in which 
the total yearly sales of a salesman are to be computed as the sum of 
the four individual sales quarters. Figure 4-9 iliustrates one method 
of expressing a solution to this problem in COBOL: 


4-22 
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MOVE @ TO TEMP. 


ADD 1ST-SALES TO TEMP. 
ADD 2ND-SALES TO TEMP. 
ADD 3RD-SALES TO TEMP. 


ADD 4TH-SALES TO TEMP GIVING TOTAL-SALES. 


igure 4-9 Explicit Programmer-Defined Temporary Work Area 


In figure 4-9, the COBOL programmer chooses to use a series of single 
ADD statements to develop the final value for TOTAL-SALES. In the 
process of computing TOTAL-SALES, a COBOL data-name, called TEMP, is 
used to develop the partial sums (i.e.,* intermediate results). The 
important point here is that the programmer explicitly defines and 
declares the temporary work area TEMP in the data division of the 
COBOL program. That is, the attributes {i.e., class, USAGE, number of 


integer and decimal places to be maintained) are specified explicitly 
by the COBOL programmer. 


Figure 4-1 below illustrates another way of expressing a solution to 
the problem: 


ADD 1ST-SALES, 2ND-SALES, 3RD-SALES, 4TH-SALES 


GIVING TOTAL-SALES. 





Figure 4-19 
Arithmetic Statement Intermediate Result Field Attributes 
Determined from Composite of Operands 
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In this example, the programmer chooses to compute TOTAL-SALES with a 
single ADD statement. Analogous to the previous example, an 
intermediate result field is required to develop the partial sums of 
the four quarterly sales quantities. In Figures 4-9, the programmer 
is cognizant of this requirement, but chose to define the intermediate 
result area TEMP explicitly in the data division of his COBOL program. 
However, for the example in Figure 4-198, the compiler defines the 
intermediate result field in a manner transparent to the COBOL source 
program. That is, the compiler allocates storage for and assigns 
various attributes to this "transparent" intermediate result field 
according to a well-defined set of rules defined by the COBOL language 
specification. In particular, the attributes of 
number-of-integer-places, number-of-decimal-places, and USAGE assigned 
by the software to the intermediate result field are a function of the 
composite of source operands in the ADD statement. (The reader should 
read the PDP-11 COBOL Reference Manual for details concerning the 
composite of operands for the arithmetic statements.) The important 
point here is that the ANS-74 COBOL language standard prescribes rules 
for determining the attributes of intermediate result fields for the 
arithmetic statements, and the language processor, the PDP-11l COBOL 
compiler, must implement those rules. 


As a final example, consider the following solution to our problem: 


COMPUTE TOTAL-SALES = 1ST-SALES + 2ND-SALES + 3RD-SALES 


+ A4TH-SALES. 





Figure 4-11 
Arithmetic Expression Intermediate Result Field 
Attributes Determined by Implementor-Defined Rules 


In Figure 4-11, the programmer solves the problem by using a _ single 
COMPUTE statement with an embedded arithmetic expression. Again, an 
intermediate result field is required and, as in Figure 4-19, is 
defined by the software. However, in defining the attributes of 
intermediate result fields for COBOL arithmetic expressions, the 
ANS-74 COBOL language standard is not as helpful to the user as it 
could be. In fact, the COBOL language standard gives almost complete 
freedom to the implementor in defining the attributes of the 
arithmetic expression intermediate resuit fields. The oniy rules 
imposed by the ANS-74 COBOL language specifications are: 


1. Arithmetic operations are to be combined without restrictions 
on the composite of operands and/or receiving fields. 


2. Each implementor will indicate techniques used in handling 
arithmetic expressions. 
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Thus, the user can and should expect differences between various 
implementations of ANS-74 COBOL. The rest of this section describes 
how the PDP-11 COBOL compiler computes the sizes of intermediate 
result fields. 


The compiler computes the size of an intermediate result field for 
each component operation of an arithmetic expression. Each operation 
can be stated as: 


OP1 OPR OP2 


where: 
OP1 is the first operand 
OPR is an arithmetic operator 
OP2 is the second operand 


The size of an intermediate result is described in terms of the number 
of integer piaces (IP) and the number of decimal places (DP). The 
symbol DPEXP represents the maximum number of decimal places in the 


: : 
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entire arithmetic expression. 


OPR 
+ and - IP = max(IP(OP1), IP(OP2)) + 1 
DP = max(DP(OP1), DP(OP2)) 
* IP = IP(OP1) + IP(OP2) 
DP = DP(OP1) + DP(OP2) 
7 IP = IP(OP1) + DP(OP2) 
DP = max (DPEXP, max(DP(OP1), DP(OP2) + 1)) 
ex For exponents that convert to one-word values, 
a = OP2 
b = OP2 + DP(OP1) 


Otherwise, 


a = 9, if IP(OP2) = 1, 
otherwise, a = 19 
b = DPEXP 
and 
IP = IP(OP1) * a 
DP = max(DPEXP, DP(OP1) * b) 


CHAPTER 5 


TABLE HANDLING 


5.1 INTRODUCTION 


With COBOL, as with any other language, any data item to which the 


program refers must be uniquely identified. This unique 
identification of data items is usually accomplished by assigning a 
unigue name to each item. However, in many applications this is 


tedious and inconvenient; often programs require too many names’ for 
items that have different names but contain the same type of 
information. Tables provide a simple solution to this problem. 
PDP-11 COBOL includes full tabie handiing capabilities as outlined for 
standard COBOL in the 1974 ANSI Standards. 


A table is a repetition of one item (element) in memory. This 
repetition is accomplished by the use of the OCCURS clause in the data 
description entry. The literal value in the OCCURS clause causes’ the 
software to duplicate the data description entry as many times as 
indicated by that value, thus creating a matrix or table. 


The elements may be initialized with the VALUE clause or with a 


procedural instruction. They may contain synchronized or 
unsynchronized data. They may be accessed only with subscripted 
procedural instructions. A subscript is a parenthesized integer or 


data name (with an integer value). The integer value represents’ the 
desired occurrence of the element. 


This chapter discusses how to set up tables and access them accurately 
and efficiently. It attempts to cover any problems that may be 
encountered while handling tables. Read it through carefully before 
setting up tables with PDP-1l1 COBOL. Section 6 of the PDP-11 COBOL 
Reference Manual for the PDP-11 contains reference information on the 
individual table handling instructions (OCCURS, USAGE IS INDEX, SET, 
and SEARCH). 


5.2 DEFINING TABLES 


To define a table with PDP-11 COBOL, simply complete a standard data 
description for one element of the table and follow it with an OCCURS 
clause. The OCCURS clause contains an integer which dictates’ the 
number of times that element will be repeated in memory, thus creating 
a table. 
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The OCCURS phrase has two formats: 
Format 1 
OCCURS integer-2 TIMES 


eae 


KEY IS data-name-2 [, data-name-3] | pad 


DESCENDING 





[ INDEXED BY index-name-1l [, index-name-2] eon 


4 






Format 2 





OCCURS integer-l TO integer-2 TIMES DEPENDING ON data-name-1 


ASCENDING 
KEY IS data-name-2 [, data-name-3] ... ae 


DESCENDING 





| INDEXED BY index-name-l [, index-name-2] an 





In either format, the system generates a buffer large enough to 
accommodate integer-2 occurrences of the data description. Therefore, 
the amount of storage allocated in either case is equal to the amount 
of storage required to repeat the data entry integer-2 times. 


The software will automatically map the elements into memory. When 
mapping a table into memory, the software follows the rules for 
mapping which depend on whether the element contains synchronized 
items or not. If they do not contain synchronized items, the software 
maps them into adjacent memory locations and the size of the table can 
be easily calculated by multiplying the size of the element times the 
number of occurrences (5X10 for the table illustrated in Figure 5-1, 
or 50 bytes of memory). 


01 A-TABLE 


03 A-GROUP PIC X(5) OCCURS 10 TIMES. 





Figure 5-1 
Defining a Table 


5.2.1 The OCCURS Phrase - Format l 


When Format 1 is used, a fixed length table is generated, whose length 
(number of occurrences) is equal to the value specified by integer-2. 
This format is useful for storing large amounts of frequently used 
reference data whose size never changes. Tax tables, used in payroll 
deduction programs, are an excellent example of where a Format 1 
(fixed length) table might be used. 


5.2.2 The OCCURS Phrase - Format 2 


Format 2 is used to generate variable length tables. When used, a 
table whose length (number of occurrences) is equal to the value 
specified by data-name-1l is generated. 
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NOTE 


Data-~name-l must always be a positive 
integer whose value is equal to or 
greater than integer-l but not greater 
than integer-2. 


Unlike format 1 tables, the number of occurrences of data items in 
format 2 tables can be dynamically expanded or reduced to satisfy user 
needs. 


By generating a variable length table, the user is, in effect, saying; 
"build me a table that can contain at least integer-l occurrences, but 
no more than integer-2 occurrences, and set its number of occurrences 
equal to the value specified by data-name-1". 


Data-name-1l always reflects the number of occurrences available for 
user access. To expand the size (number of occurrences available for 
use) of a table, the user need only increase the value of data-name-1 
accordingly. 


Likewise, reducing the value in data-name-l will reduce the number of 
occurrences available for user access. 


5.3 MAPPING TABLE ELEMENTS 


As mentioned in Section 5.2, when the software detects an OCCURS 
clause in an unsynchronized item, it maps the table elements into 
adjacent locations in memory. Consider the following data description 
cof a simple table and the way it is mapped into memory: 


Table Description: O01 A-TABLE. 
03 A-GROUP PIC X(5) OCCURS 10 TIMES. 


Memory Map: 


i oe 


A-GROUP A-GROUP A-GROUP A-GROUP 





Figure 5-2 
Mapping a Table into Memory 


The data description in Figure 5-2 causes the software to set up ten 
items of five bytes each (elements) and place them in adjacent 
ascending memory locations for a total of 50 character positions, thus 
creating a_ table. Since the length of each A-GROUP element is odd 
(5), the memory addresses of each subsequent element will alternate 
between odd and even locations. 


The SYNCHRONIZED clause causes the software to add a fill byte to 
items that contain an odd number of bytes, thereby making the number. 
of bytes in that item even. This ensures that each subsequent 
occurrence of the element will not alternate between odd and even 
addresses, but will map the same (odd or even) as the first repetition 
of that element. 
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If the data description of A-GROUP contained a SYNCHRONIZED clause, 
the software would map it quite differently. If A-GROUP were 
synchronized, it would expand its length to three words. The item 
will, by default, be synchronized to the left occupying the first five 
characters of the three words. The software supplies a #§ padding 
character to fill out the third word. This padding character is not a 
part of the A-GROUP element and table instructions referring to 
A-TABLE will not detect the presence or absence of the character. 


The padding character does, however, affect the overall length of the 
group item and, hence, the table. Without the SYNCHRONIZED clause, 
A-TABLE required only 50 character positions; now, with the clause, 
it requires 60 character positions. (This length includes the last 
padding character -- following the tenth element in the table.) 


Although the SYNCHRONIZED clause has little value when used with 
alphanumeric fields, an understanding of the concept is essential 
before attempting to use COMP and INDEX data items in tables. The 
software automatically synchronizes all COMP and INDEX usage data 
items, and will most probably alter the size of any table (often 
drastically) that contains these data types. Consider the following 
illustration of a synchronized data item being mapped by the software: 


Table Description: 01 A-TABLE. 
03 A-GROUP OCCURS 20 TIMES. 


05 ITEM1 PIC x. ]1--ITEM1 
05 ITEM2 PIC S999 COMP. 2--ITEM2 
S--SLACK 

BYTE 


Memory Map: 


=e | rrr] iv{ v | vi | vit | vriz | 
| 1 Vs 2l2 [1 Ysf2i2 [ive 2]2 | 1 sy 22 | 


A-GROUP A-GROUP A-GROUP A-GROUP 





Figure 5-3 
Synchronized COMP Item in a Table 


Since the software synchronizes the ITEM2 fields (COMP), these fields 
each occupy a Single word in memory; thus, a slack byte follows each 
occurrence of ITEM1. Each repetition of A-GROUP consumes four bytes 
of memory -- one byte for ITEM], one byte for the slack byte, and two 
bytes for ITEM2. A-TABLE, then, requires 80 bytes of memory (20 
elements of four bytes each). 


Now, consider the effect of adding a 1l-byte field to A-TABLE. If we 
place the field between ITEMl and ITEM2, it will take the space 
formerly occupied by the slack byte. This has the effect of adding a 
data byte but leaving the size of the table unchanged. Consider the 
following iilustration: 
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Table Description: 01 A-TABLE. 
03 A-GROUP OCCURS 20 TIMES. 
05 ITEM1 PIC xX. 
05 ITEM3 PIC X. 
05 ITEM2 PIC S999 COMP. 





1--ITEM1 
Memory Map: 2--ITEM2 
3--ITEM3 
words 
bytes 





A-GROUP A-GROUP A-GROUP 





Figure 5-4 
Adding a Field without Altering the Table Size 


If, however, we place the l-byte field after ITEM2, it has the’ effect 
of adding its own length plus another slack byte. Now, each element 
requires six full bytes and the complete table consumes 120 bytes of 
memory (6X20) i This is due to the fact that the first repetition of 
ITEM] falls on an even byte and, in order to keep the mapping of each 
A-GROUP element the _ same, the software allocates each successive 
repetition of ITEM1 to an even byte address. Thus, it assigns ITEM3 
to the even byte of the third word and adds a slack byte to guarantee 
that the next element begins on an even byte. Consider the following 
illustration: 


| able Descri Lon: O01 A-TABLE. | 


03 A-GROUP OCCURS 20 TIMES. 
OS: IVEML. PIC “Xs 
05 ITEM2 PIC S999 COMP. 
05. PPEM3: PIC:-x. 


Memory Map: 


Odd or Even EOEOEOEOEOEOEO = 


words Crp ar[rit|sy |v [vi [vir[vird tx] 


bytes IBN </ PAPAEN/</ 6/2) PAPA) BR/S/AP RELY, 


A-GROUP A-GROUP 





Figure 5-5 
Adding One Byte which Adds Two Bytes 
to the Element Length 


NOTE 


The illustrations in this section show 
each byte with an even address (E) as 
the leftmost byte, and each byte with an 
odd address (0) as the rightmost byte. 
(The two bytes, odd and even, are 
reversed in actual memory.) 
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If, however, we use a FILLER byte to force the first allocation of 
ITEM] to occur on an odd byte, A-GROUP again requires only four bytes 
and no slack bytes. Figure 5-6 illustrates this. Since the FILLER 
item occupies the even byte of the first word, ITEM1 falls on an odd 
byte. The software requires that each repetition of ITEM1 must be an 
even number of bytes in length in order to guarantee that the 
synchronized item(s) will map onto word boundaries. No slack bytes 
are needed and A-GROUP elements are again only four bytes long, and 
A-TABLE requires only 81 bytes. 


Table Description: 01 A-TABLE. 
03 FILLER PIC X. 
03 A-GROUP OCCURS 20 TIMES. 
05 ITEM1 PIC X. 
05 ITEM2 PIC S999 COMP. 
05 ITEM3 PIC X. 


Memory Map: 


odd or even EO £0 


EO EO EO 
words 
bytes PF] 2[2 | 3fa | 2f2] 3ji] 2f2 | 3y | 


FILLER A-GROUP A-GROUP A-GROUP 





Figure 5-6 
Forcing an Odd Address By Adding a 1-Byte FILLER 
Item to the Head of the Table 


If we try to force ITEM1 onto an odd byte with a SYNCHRONIZED RIGHT 
clause, the software maps ITEM] into the odd byte, but prohibits all 
repetitions of the element from using the even byte. Thus, the first 
repetition of A-GROUP has a slack byte at its beginning and, so that 
the next element can begin (with a slack byte) at an even address, 
another slack byte (odd) following ITEM3. This expands the element 
length to six bytes and the table length to 120 bytes. 


oe 
Table Description: 01 A-TABLE. 
03 A-GROUP OCCURS 20 TIMES. 
05 ITEM1 PIC X SYNCHRONIZED RIGHT. 
05 ITEM2 PIC S999 COMP. 
05 ITEM3 PIC X. 





Memory Map: | 
Odd or Even EO EO EO EO EO FEO EO EO £0 cea 
words 
| bytes UA | 212 | 3ySAy/sii | 2}2 | 3sAysyl | 2)2 | 3487 | 
Na a ee ee ee es 
| A-GROUP A=GROUP A-GROUP ese | 
Figure 5-7 


The Effect of a SYNCHRONIZED RIGHT Clause Instead 
of a FILLER Item as shown in Figure 5-6 
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To determine how the software will map a given table, apply the 
following two rules: 


1. The software maps all items in the first repetition of a 
table element into memory words as with any item properly 
defined with a data description, obeying any implicit or 
explicit synchronization requirements. 


2. If the first repetition contains any elementary items with 
implicit or explicit synchronization, the software maps each 
successive repetition of the element into memory words in the 
same way as the first repetition. It does this by adding one 
slack byte, if necessary, to make the size of the element 
even. 


5.3.1 Initializing Tables 


If a table contains only DISPLAY items, it can be set to any desired 
initial value (initialized). To initialize a table, simply specify a 
VALUE phrase on the record level preceding the item containing the 
OCCURS clause. The sample data definitions, below, will set up 
initialized tables: 


Table Description: 01 A-TABLE VALUE IS "JANFEBMARAPRMAY 
= JUNJULAUGSEPOCTNOVDEC". 
03 MONTH-GROUP PIC XXX USAGE DISPLAY 
OCCURS 12 TIMES. 


Memory Map: 


words 
byte contents[J|A|N{F|E|B[M|A[RIA|P/R|M J 
ee 


MONTH-GROUP MONTH-GROUP 
MONTH-GROUP MONTH-GROUP 
MONTH-GROUP MONTH-GROUP 
MONTH-GROUP MONTH-GROUP 





Figure 5-8 
Initializing Tables 


Often a table is too long to initialize with a single literal, or it 
contains items that cannot be initialized (numeric, alphanumeric, or 
COMP). These items can be individually initialized by redefining the 
group level preceding the level that contains the OCCURS clause. 
Consider the following sample table descriptions: 
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Table Description: 01 A-RECORD-ALT. 
05 FILLER PIC XX VALUE "Ax". 
05 FILLER PIC 99 COMP VALUE 1. 
05 FILLER PIC XX VALUE "BX". 
05 FILLER PIC 99 COMP VALUE 2. 


01 A-RECORD REDEFINES A-RECORD-ALT. 


03 A-GROUP OCCURS 26 TIMES. 
05 ITEM] PIC xX. 
05 ITEM2 PIC S99 COMP. 


Memory Map: 


words 
byte contents at LAL ee i 
initialization tiie — SO 

A-GROUP A-GROUP 





Figure 5-9 
Initializing Mixed Usage Fields 


In the preceding example, the slack bytes in the alphanumeric fields 
(ITEM1) are being initialized to X. 


Table Description: 01 A-RECORD-ALT. 
03 FILLER PIC X(30) VALUE IS 
"AAAAAAAAAABBBBBBBBBBCCCCCCCCCC". 
03 FILLER PIC X(30) VALUE IS 


"DDDDDDDDDDEEEEEEEEEEFFFFFFFFFF". 
(etc.) 


01 A-RECORD REDEFINES A-RECORD-ALT. 
03 ITEM] PIX X(10) OCCURS 26 TIMES. 


Memory Map: 


word VIII 
byte [B/B/B/B/B/B | B/B/B/BIC|C| 
~~) eee 


contents at 
initialization 
time 





Figure 5-10 
Initializing Alphanumeric Fields 


In the preceding example, each FILLER item initializes three 10-byte 
table elements. 


When redefining or initializing table elements, allow space for any 
slack bytes that may be added due to synchronization (implicit or 
explicit). The slack bytes do not have to be initialized; however, 
they may be and, if initialized to an uncommon value, they may even 
serve as a debugging aid for situations such as a statement referring 


to the record level above the OCCURS clause or another record 
redefining that level. 
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Sometimes the length and format of table items are such that they 
would best be initialized by statements in the Procedure Division. 
This initialization coding could be executed once and then overlaid 
(due to the automatic segmentation feature) if the entire Procedure 
Division is too large to be held in memory at one time. 


Once the OCCURS clauses have established the necessary tables, the 
program must be able to access the elements of those tables 
individually. Subscripting and indexing are the two methods provided 
by COBOL for accessing individual elements. 


5.4 SUBSCRIPTING AND INDEXING 


To refer to a particular element within a table, simply follow the 
name of the desired element with a parenthesized subscript or index. 
A subscript is an integer or a data-name that has an integer value; 
the integer value represents the desired occurrence of the element -- 
an integer value of 3, for example, refers to the third occurrence of 
the element. An index is a data-name that has been named in an 
INDEXED BY phrase in the OCCURS clause. 


5.4.1 Subscripting with Literals 


A literal subscript is simply a parenthesized integer whose value 
represents the occurrence number of the desired element. In figure 
5-11, the literal subscript in the MOVE instruction (2) causes’ the 
software to move the contents of the second element of the table, 
A-TABLE, to I-RECORD. 


01 A-TABLE. 
Table Description 03 A-GROUP PIC X(5) 
OCCURS 10 TIMES. 





Procedural Instruction MOVE A-GROUP(2) TO I-RECORD. 


Figure 5-11 
Literal Subscripting 


If the table has more than one level (or dimension), follow the name 
of the desired item with a list of subscripts, one for each OCCURS 
clause to which the item is subordinate. The first subscript in the 
list applies to the first OCCURS clause to which the item is 
subordinate. (This is the most encompassing level -- A-GROUP in the 
following example.) The second subscript in the list applies to the 
next most encompassing level, and the last subscript applies to the 
lowest level OCCURS clause being accessed (or the desired occurrence 
number of the item named in the procedural instruction -- ITEM5 in the 
following example). 


Consider Figure 5-12; the subscripts (2,11,3) in the MOVE instruction 
cause the software to move the third repetition of ITEM5 in the 
eleventh repetition of ITEM3 in the second repetition of A-GROUP to 
I-FIELD5. (For illustration simplicity, I-FIELD5 is not defined.) 
(ITEM5(1,1,1) would refer to the first occurrence of ITEM5 in the 
table and ITEM5(5,20,4) would refer to the last occurrence of ITEMS.) 


5-9 
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O01 A-TABLE. 
03 A-GROUP OCCURS 5 TIMES. 
05 ITEM] PIC X. 
Table Description 05 ITEM2 PIC 99 COMP OCCURS 20 
TIMES. 


05 ITEM3 OCCURS 20 TIMES. 
07 ITEM4 PIC X. 
07 ITEM5 PIC XX OCCURS 4 TIMES. 


Procedural Instruction MOVE ITEM5(2, 11, 3) TO I-FIELD5. 


Figure 5-12 
Subscripting a Multi-Dimensional Table 





NOTE 


Since ITEM5 is not subordinate to ITEM2, 
an occurrence number for ITEM2 is not 
permitted in the subscript list. 


Figure 5-13 summarizes the subscripting rules for each of the above 
items and shows the size of each field in bytes. 


NUMBER OF SUBSCRIPTS 
REQUIRED TO REFER TO 
THE NAMED FIELD 


A-TABLE 
A-GROUP 
ITEM1 


ITEM2 
ITEM3 
ITEM4 
ITEM5 





* Plus a slack byte 


Figure 5-13 
Subscripting Rules for a 
Multi-Dimensional Table 


5.4.2 Operations Performed by the Software 


When a literal subscript is used to refer to an item in a table, the 


software performs the following steps to determine the exact address 
of the item: 


1. The compiler converts the literal to a i-word binary value. 


2. The compiler range checks the subscript value (the value must 
not be less than 1 nor greater than the number of repetitions 
specified by the OCCURS clause) and prints a diagnostic 
message if the value is out of range. 


3. The compiler decrements the value of the subscript by 1 and 
multiplies it by the size of the item that contains the 
OCCURS clause corresponding to this subscript, thus forming 


an index value; it then stores this value, plus the literal 
subscript, in the object program. 


5.0 
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4, At object execution time for a fixed length table, the run 
time system adds the index value (from 3 above) to a base 
address, thus determining the address of the desired item. 
For a variable length table reference, the procedure for 
fixed length tables is preceded by the procedure described in 
Section 5.4.6. 


5.4.3 Subscripting with Data-Names 


As discussed earlier in this section, subscripts may also be specified 
using data-names instead of literals. To use a data-name as a 
subscript, simply define it as a numeric integer (COMP or DISPLAY). 
It may be signed, but the sign must be positive at the time it is used 
as a subscript. 


The sample subscripts in figure 5-14 refer to the same element 
accessed in Figure 5-12, (2, 11, 3). 





O01 KEY1 PIC 99 USAGE DISPLAY. | 


Data Descriptions 
of Subscript data-names O01 KEY2 PIC 99 USAGE COMP. 
OL Wat? Se te at ae ao 


oo 
| | U NOELO Pit OFF. | 


| | MOVE 2 TO KEY1. 
MOVE 11 TO KEY2. 
MOVE 3 TO KEY3. 
GO TO TABLERTN. 
TABLERTN. 
MOVE ITEM5(KEY1 KEY2 KEY3) TO 
| I-FIELD5. 

















Procedural Instructions 





Figure 5-14 
Subscripting with Data-Names 


5.4.4 Operations Performed by the OTS 


When a data-name subscript is used to refer to an item in a table, the 
OTS performs the following steps at object execution time: 


l. If the data-name's data type is DISPLAY, the software 
converts it to a l-word binary value. 


2. For fixed length tables, the software range checks’ the 
subscript value (the value must not be less than 1 nor 
greater than the number of repetitions specified by the 
OCCURS clause) and terminates the object program (with a 
diagnostic message) if it is out of range. For variable 
length tables, the procedure described in Section 5.4.6 is 
followed. 


3. The software decrements the value of the subscript by 1 and 
multiplies it by the size of the item that contains the 
OCCURS clause corresponding to this subscript, thus forming 
an index value. 


4. The software adds the index value (from 3 above) to a base 
address, thus determining the address of the desired item. 
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5.4.5 Subscripting with Indexes 


The same rules apply for the specification of indexes as apply to 
subscripts except that the index must’ be named in the INDEXED BY 
phrase of the OCCURS clause. 


An index-name item (an item named in the INDEXED BY phrase of the 
OCCURS clause) has the ability to hold an index value. (The index 
value is the product formed in step 3 of the operations performed by 
the software for literal or data-name subscripts -- the relative 
location, within the table, of the desired item.) 


The compiler allocates a 2-part data item for each name that follows 
an INDEXED BY phrase. These index-name items cannot be accessed as 
normal data items; they cannot be moved about, redefined, written to 
a file, etc. However, the SET verb can change their values and 
relation tests can examine their values. One part of the 2-part 
index-name item contains a subscript value and the other part contains 
an index value. Consider the following illustration: 


INDEX PART 
SUBSCRIPT PART 





Figure 5-15 
Index-Name Item 


Whenever a SET statement places a new value in the subscript part, the 
software performs an index value computation and stores the result in 
the index part. Only the subscript part of the item acts as a sending 
or receiving field. The index part is never altered by any other 
operation and is never moved to another item. It is used only when 
the index-name is used as an index referring to a table item. The 
Sample MOVE statement in Figure 5-16 would move the contents of the 
third repetition of A-GROUP to I-FIELD. (For illustration simplicity, 
once again, I-FIELD is not defined.) 


01 A-TABLE. 
Table Description 03 A-GROUP OCCURS 5 TIMES 
INDEXED BY IND-NAME. 


Procedural Instructions SET IND-NAME TO 3. 


MOVE A-GROUP (IND-NAME) TO I-FIELD. 
ea Ca eS Cee ee re ee 





Figure 5-16 
Subscripting With Index-name Items 


5.4.6 Operations Performed by the OTS 


The OTS performs the following steps when it executes the SET 
statement: 


l. The OTS converts the contents of the sending field of the SET 
statement to a l-word binary value. 


2. The OTS range checks the value (the value must not be less 
than 1 nor greater than the number of repetitions specified 
in the OCCURS clause) and terminates the object program with 
a diagnostic message if it is out of range. 
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3. The OTS decrements the value by 1 and multiplies it by the 
Size of the item that contains the OCCURS clause, thus 
forming an index value. 


For fixed length tables, once the SET statement has been executed and 
the software has encountered the index-name item as an index, it only 
has to add the index value (from 3 above) to a base address to 
determine the address of the desired item. Since this is the only 
action performed, the execution speed of a procedural statement with 
an indexed data-name is equivalent to a reference with a literal 
subscript. 


For a variable length table, when the index-name is encountered as an 
index, the procedure described in Section 5.4.6 is invoked before 
following the fixed length table logic. However, the SET statement 
itself is not impacted by the fixed/variable characteristic of the 
associated table. 


PDP-11 COBOL initializes the value of all index-name items to a 
subscript value of 1 (index value of 0), hence an attempt to use an 
index-name item as an index before it has been the receiving field of 
a SET verb will not result in an out-of-range termination. 


NOTE 


Initialization of index-name items is an 
extension to the ANSI COBOL standards. 
Users concerned with writing COBOL 
programs that adhere to standard COBOL 
should not rely on this feature. 


5.4.7 Relative Indexing 


To perform relative indexing, when referring to a table item, simply 
follow the index-name with a plus or minus’ sign and an integer 
literal. Relative indexing, albeit easy to use, causes additional 
overhead to be generated each time a table item is referenced in this 
fashion. At compile time, the compiler has to compute the index value 
corresponding to the specified literal; and transfer this index value 
to the object file. At object run time, the index value for the 
literal is added to (+) or subtracted from (-) the index value of the 
index-name. The resulting index value is stored in a temporary 
location. The OTS adds this temporary index value to the base address 
of the table to determine the address of the desired table item. At 
this point, a range check is performed on the temporary index value to 
insure that the resulting index is within the permissible range for 
the table. 


For fixed length tables, this index manipulation is’ relatively 
straightforward. The size of the table is known at compilation time, 
and this size is passed along to the OTS in the object file. A simple 
compare against this fixed value is all that is required to determine 
if a given index value is within the permissable range for the table. 


For a variable length table, however, the process is more involved. 
The current number of occurrences (data-name-1l) for the table must be 
determined and range checked; the index value corresponding to the 
current number of occurrences must be calculated; then the temporary 
index value must be range checked using the current number of 
occurrence's index value. 


B= 13 
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The object time overhead required for the relative indexing of 
variable length tables is significantly greater than that required for 
fixed length tables. In either case, the index portion of the 
index-name is not altered. If any of the range checks reveals an 
illegal (out of range) value, execution is terminated with an 
apropriate error message. 


The sample MOVE instruction in Figure 5-17 moves the fourth repetition 
of A-GROUP to I-FIELD if IND-NAME has not been altered with a SET 
verb. 


| MOVE A-GROUP(IND-NAME + 3) TO I-FIELD. | 


Figure 5-17 
Relative Indexing 


The actual operation of accessing a table element is shorter at run 
time since the compiler has calculated the index value of the literal 
at compile time and has stored it in the object program ready for use. 
Relative indexing, therefore, involves two additions and a range check 
during object execution. It leaves the index-name item unaltered. 


5.4.8 Index Data Items 


Often a program will require that the value of an index-name item be 
stored outside of that item. It is for this purpose that PDP-1l1l COBOL 
provides the index data item. 


Index data items are l-word binary integers with implicit 
synchronization. (The l1-word size corresponds to the subscript part 
of the index-name item.) They must be declared with a USAGE IS INDEX 
phrase and they may be modified (explicitly) only by the SET 
statement. 


Subscript Part ——=__-.[ 


Figure 5-18 
Index Data Item 


Since index data items are considered to contain only the subscript 
part of an index-name item, when a SET statement "moves" an index-name 
item to an index data item, only the subscript part is moved. 
Likewise, when a SET statement "moves" an index data item to an 
index-name item, a new index value is computed by the software. This 
is done to guarantee that an index-name item will always contain a 
good index value. 


The only advantage gained by using index data items over numeric, COMP 
items is that the data description is shorter, easier to write, and 
more self-documenting. Further, the restrictions placed on access to 
index items may be useful in debugging the program. 


5.4.9 The SET Statement 


The SET statement alters the value of index-name items and copies 
their value into other items. When used without the UP BY/DOWN BY 
clause, it functions like a MOVE statement. Figure 5-19 illustrates 
the legal data movements that the SET statement can perform. 
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| INDEX-NAME ITEM | 


NUMERIC LITERAL (INDEX PART) INDEX DATA ITEM 
(SUBSCRIPT PART)“™——yS 


NUMERIC DATA NAME INDEX-NAME ITEM 
(COMP OR DISPLAY) 


(SUBSCRIPT PART) 





Figure 5-19 
Legal Data Movement with the SET Statement 


The SET statement may be used with the UP BY/DOWN BY clause to alter 
the value of an index-name item arithmetically. The numeric literal 
is added to (UP BY) or subtracted from (DOWN BY) the subscript part, 
and the index part is recalculated by the software after the 
appropriate range check against the number of repetitions for the 
table. The SET statement is not affected by whether the table is 
fixed or variable length. 


5.4.10 Referencing a Variabie Length Table Element at OTS Time 


At OTS time, when a procedural reference involves an element in a 
variable length table, the following procedure is used: 


1. Determine the number of occurrences in the table (the value 
contained in data-name-l), and verify its legality. 


(integer-1l <= data-name-l <= integer-2) 
2. Verify that the subscript is within the legal range. 
(subscript <= data-name-1) 


If any of the above checks fails, execution is terminated with an 
appropriate error message. 


5.4.11 Referencing a Dynamic Group at OTS Time 


A dynamic group is defined as a group item that contains a subordinate 
item that is a variable length table. At OTS time, when a dynamic 
group is referenced, the following procedures are followed: 


l. The number of occurrences of the subordinate variable length 
table is determined, and checked for legality; ises; 
integer-1<=data-name-1l<=integer-2. If this check fails, 
execution terminates and the appropriate error message is 
issued. 


2. The size of the dynamic group is calculated. The number of 
occurrences of the variable length table (data-name-l) is 
Multiplied by the size of one table entry. The resulting 
number is then added to the fixed size of the dynamic group. 
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NOTE 


The fixed size of a dynamic group is the 
size of the group up to but not 
including the variable length table. 


5.4.12 The SEARCH Verb 


The SEARCH verbd has two formats: Format 1, which performs a 
seguential search of the specified table beginning with the current 
index setting; and Format 2 which performs a selective (binary) 
search of the specified table, beginning with the middle of the table. 


Both formats allow the programmer to specify imperative statements 
within the SEARCH verb. At OTS time, an imperative statement 
contained within a search verb is executed only when one of the exit 
paths (success or failure) is taken. 


The failure path is defined either explicitly by the AT END statement, 
in which case the imperative statement which follows it is executed; 
or by default, in which case control is passed to the next procedural 
sentence. In either case (success or failure), after an imperative 
statement is executed, control is passed to the next procedural 
sentence. 


5.4.13 The SEARCH Verb - Format l 


Format 1 directs the OTS to search the indicated table sequentially. 
The OCCURS clause for the table being searched must contain the 
INDEXED by phrase. Unless otherwise specified in the SEARCH 
statement, the first index is the controlling index for the table 
search. The search begins with the current index setting, and 
progresses through the table, augmenting the index by one as each 
occurrence is interrogated. If any of the specified conditions is 
true (success), the associated imperative statement is executed; the 
search exits; and the index remains at the current setting. 


If the possible number of occurrences for the table is exhausted 
before any of the specified conditions are met, the specified failure 
exit path is taken. That is, either the AT END exit path (if 
specified) is taken, or control is passed to the next procedural 
sentence. 


Figure 5-20 contains an example of using the SEARCH verb to search a 
table in a serially. 


Associated with Format 1 is the optional VARYING phrase. This phrase 
can be specified by using any of the following methods: 


oa 1 nn = 7 
fault - phrase omitted 


1. @ 


@M 


2. VARYING index-name-n 
3. VARYING identifier-2 


4, VARYING index-name-2 
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NOTE 


The following is true regardless of which of the 
above methods is used. 


a. An index name associated with the table is methodically 
augmented by one, by the OTS, for each cycle of the 
serial search. This controlling index, when compared to 
the allowable number of occurrences for the table, 
dictates the permissible range of search cycles at OTS 
time. When an exit occurs (success or failure), this 
index remains at the current setting. 


b. The OTS will not initialize the index when the _ search 
begins. It is the programmers responsibility to insure 
that the initial index setting is the appropriate one. 
The OTS will begin processing the table with the setting 
it finds when the search is initiated. 

When method 1 is used, the first index name (in 


—-name-l) associated 
Mw ee 2 ~fJ; £BWwesevvanre 


with the table is used as the controlling index. Only this index is 
set to consecutive values by the OTS serial search processor. See 
Figure 5-20, Example 2, for an example of using method l. 


When method 2 is used, index-name-n is any index that is associated 
with the table being searched. It becomes the controlling index for 
the table. It alone is set to consecutive values by the OTS search 
processor. See Figure 5-20, Example 3, for an example of using method 
Bis 


When method 3 is used, identifier-2 is augmented by one each time the 
first index (controlling index) for the table is augmented by one. 
Identifier-2 is not a substitute index. It merely allows’ the 
programmer to maintain an additional pointer to elements within a 
table. See Figure 5-20, Example 4, for an example of method 3. 


When method 4 is used, index-name-2 is an index that is associated 
with a table other than the one being searched. Each time the 
controlling index (lst index for the table) of the searched table is 
augmented, index-name-2 is also augmented. See Figure 5-20, Example 
os 


5.4.14 The SEARCH Verb - Format 2 


Format 2 is used to direct the OTS to search the indicated table 
selectively. The selective (binary) search is predicated upon the 
ASCENDING/DESCENDING KEY attributes of the table being searched. 
Therefore, an ASCENDING and/or DESCENDING KEY(s) must be specified in 
the OCCURS clause that defines the table, to inform the OTS that the 
keys are stored within the table in ascending or descending order. 


The INDEXED BY phrase must also be specified. When the binary search 
is executed, the OTS uses the first or only index associated with the 
table as the controlling index for the search. 
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The selective (binary) search is implemented in the OTS as follows: 


l. 


ht wee 5-20 Wee mmm? L£ == ee Pa 3 ee ae Sao ee eS ain a 
igure o VU, BKalipie oO, cor an e@xampie Or Searcning a ctavnie u 


The OTS examines the range of permissible values for the 
index of the table being searched; selects the median value; 
and assigns this median value to the index. 


The OTS then proceeds to process the sequence of simple tests 
for equality, beginning with the first, with the index set to 
the median value. 


If all of the tests for equality are true (success), the 
search is terminated; the associated imperative statement is 
executed; the search exits; and the index retains its 
current value. 


If any of the tests for equality is false, the following 
results occur. 


a. The OTS determines if all of the possible occurrences for 
the table have been tested. If the table has been 
exhausted, the imperative statement which accompanies the 
AT END statement (if specified) is executed. In either 
case, control is passed to the next procedural statement. 


b. The OTS will now determine which half of the table is to 
be eliminated from further consideration. This 
determination is predicated on whether the key being 
tested is in ascending or descending order, and whether 
the test failed because of a greater than or less’ than 
comparison. For example, if the key values being tested 
are stored in ascending order, and the median table 
element being tested iS greater than the value being 
tested for equality, the OTS will assume that all key 
elements following the one tested are also greater than 
the value being tested for equality. Therefore, the 
lower half of the table, those items which follow the 
current index setting, are no longer in contention. 


c. Once the direction of search is determined, half of the 
table is eliminated from further consideration. A new 
range of permissible index values is computed from the 
remaining half of the table. 


d. Processing begins all over again from step l. 


w 
a 
pam 
te] 


Format 2 of the SEARCH verb. 
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FED=TAX=TABLES, 


Ge 


Be 


ALLOWANCE@DATA, 
@3 FILLER PIC X¢7@) VALUE 
"2a0idua 
"2202882 
"6304320 
"8405769 
"8527280 
"608640 
"@710082 
"8811522 
"8912962 
"1a1uaaas, 
ALLOWANCE@TABLE REDEFINES ALLOWANCE@DATA, 
O3 FED=ALLOWANCES OCCURS 1@ TIMES 
ASCENDING KEY IS ALLOWANCE#NUMBER 
INDEXED BY IND@{, 
4 ALLOWANCE=*NUMBER PIC XX, 


Q@4 ALLOWANCE PIC 999V99, 
@2 SINGLES*DEDUCTION@DATA, 
@3 FILLER PIC x(€112) VALUE 
"G2S0@8670000G016 
"4672211800067229 
"1150018390163223 
"1830024990319621 
"2400027980439326 
"279AG34690540730 
"THEAB99OS9TUI734", 
@2 SINGLES=DEDUCTION=TABLE REDEFINES SINGLES@=DEDUCTION@=DATA, 
43 SINGLES=TABLE OCCURS 7 TIMES 
ASCENDING KEY IS SeMIN@eRANGE SeMAY=RANGE 
INDEXED BY IND@2, TEMP@INDEX, 
G4 S#MINeRANGE PIc 999V99, 
@4 SeMAX#RANGE PIC 999V95, 
24 S§#TAX PIC 99V99, 
@4 S=PERCENT PIC V99, 
A2 MARRIED*PEDUCTION@DATA, 
@3 FILLER PIC X€119) VALUE 
"94890996090000017 
"AIOAA1T3IAAAA81L 62a 
"173002646000235617 
"2640934600239932e5 
"34680433000595328 
"4330@5aq00RR38932 
"59000999991053336", 
@2 MARRIED@*DEDUCTION@ TABLE REDEFINES MARRIED@DEDUCTION@DATA, 
@3 MARRIED*TABLE OCCURS 7 TIMES 
ASCENDING KEY IS MeMIN@RANGE MeMAX@RANGE 
INDEXED BY IND=@, IND#3, 
24 MeMIN@RANGE PIC 999V99. 
Q@4 MeMAXwRANGE PIC 999V99, 
@4 MeTAX PIC 999V99, 
94 MePERCENT PIC v99, 
TEMPe INDEX USAGE INDEX, 





Figure 5-20 
Example of Using SEARCH 
To Search a Table 
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Example 1 
SINGLE, 


IF TAXABLE@INCOME < 92499 
GO TO END=FED=COMP, 
SET INDw2 TO 1, 
SEARCH SINGLES@TABLE VARYING IND@2 AT END 
GO TO TABLE=2"ERROR 
WHEN TAXABLE@® INCOME @ SeMIN@RANGE(CIND@=2) 
MOVE SeTAX(IND#2) TO FEDeTAX@DEDUCTION OF 
OUTPUT=MASTER 
GO TO STORE*FED@=TAX 
WHEN TAXABLE@ INCOME € SeMAX@RANGE(CIND@Q) 
SUBTRACT S=eMIN@RANGECIND™2) FROM TAXABLE@INCOME 
MULTIPLY TAXABLE@INCOME BY S@PERCENTCIND=2@) ROUNDED 
ADD TAXABLE@INCOME TO FED@TAX@DEDUCTION OF 
OUTPUT@=MASTER, 


SINGLE, 
IF TAXABLE*=INCOME «< 92499 
GO TO END=FED=COMP, 
SET INO#2 TO 1, 
SEARCH SINGLES@TABLE VARYING INDe2 AT END 
GO TO TABLE=2©ERROR 
WHEN TAXABLE@#INCOME @ SeMIN@RANGE (CIND]2) 
MOVE SeTAXCIND@2) TO FEDeTAX@DEDUCTION OF 
OUTPUT= MASTER 
GO TO STORE#FED=TAX 
WHEN TAXABLE@INCOME < SmMAX@RANGECTIND@>) 
SUBTRACT SeMIN@RANGECIND@=2) FROM TAXABLE@INCOME 
MULTIPLY TAXABLE*INCOME BY SePERCENT(CIND#2) ROUNDED 
ADD TAXABLE*INCOME TO FED*TAX@DEDUCTION OF 
QOUTPUT=MASTER, 


Example 3 
MARRIED, 


Example 2 
| 
IF TAXABLE@INCOME « 4799 
MOVE ZEROS TO FED@TAX@DEDUCTION OF QUTPUT=MASTER, 
GO TO END@FEDeCOMP, 
SET IND#=3 TO 1, 
SEARCH MARRIED@TABLE VARYING IND#3 
AT END GO TO TABLE#3eERROR 
WHEN TAXABLEe INCOME & MeMINe@RANGECIND®3) 
MOVE MeTAX(CIND=3) TO FED@eTAX@DEDUCTION OF OUTPUTeMASTER, 
GO TO STORE@FED@TAX, 
WHEN TAXABLE@ INCOME ¢« MeMAX@RANGECIND@3) 
MOVE MeTAXCIND@#3) TO FEDeTAX#DEDUCTION OF OUTPUT@MASTER, 
SUBTRACT M=MIN@RANGE(IND@3) FROM TAXABLE@INCOME ROUNDED, 
MULTIPLY TAXABLE@INCOME BY MePERCENTCIND#3) ROUNDED, 
ADD TAXABLE@ INCOME TO FEDeTAX@DEDUCTION 
OF OUTPUT*=MASTER ROUNDED, 
GO TO STORE=FED@TAX, 





Figure 5-20 (Cont.) 
Example of Using SEARCH 


To Search a Table 
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Example 4 


SINGLE, 
IF TAXABLE@INCOME < @2499 
GO TO END=FED=COMP, 
SET INDe2 TO 1, 
SEARCH SINGLES=TABLE VARYING TEMPeINDEX AT END 
GO TO TABLE#2ERROR 
WHEN TAXABLE* INCOME @ S=MIN@RANGECIND@2) 
MOVE SeTAXCIND#2) TO FED*=TAX=DEDUCTION OF 
OUTPUT@MASTER 
GO TO STORE*FED@=TAX 
WHEN TAXABLE®INCOME « SmMAX™RANGECIND@=2) 
SUBTRACT SeMIN@RANGECIND=2) FROM TAXABLE* INCOME 
MULTIPLY TAXABLE@INCOME BY SePERCENTCIND@=2) ROUNDED 
ADD TAXABLE*INCOME TO FED@TAX=DEDUCTION OF 
OUTPUT=MASTER, 


Example 5 


SINGLE, 
IF TAXABLE=INCOME < 92499 
GO TO END=FED@COMP, 
SET INDe2 TO 1, 
SEARCH SINGLES@TABLE VARYING IND@@ AT END 
GO TO TABLE*2=eERROR 
WHEN TAXABLE@INCOME = SeMIN@RANGECIND#=2) 
MOVE SeTAXCIND|=2) TO FED*TAX=DEDUCTION OF 
OUTPUT=MASTER 
GO TO STORE=FEDeTAX 
WHEN TAXABLE®@INCOME < SeMAX@RANGECIND@2) 
SUBTRACT SeMIN@RANGECIND=2) FROM TAXABLE®@INCOME 
MULTIPLY TAXABLE@INCOME BY S=PERCENTCIND=2) ROUNDED 
ADD TAXABLE@INCOME TO FEDeTAX=DEDUCTION OF 
OUTPUT=MASTER, 


Example 6 


FED=DEDUCT=COMPUTATION, 
SET IND=i TO 1, 
SEARCH ALL FED=ALLOWANCES AT END GO TO TABLE@1*ERROR 
WHEN ALLOWANCE@NUMBERCIND=1) @ NR@®DEPENDENTS OF 
OUTPUT=MASTER, 
SUBTRACT ALLOWANCE(IND={) FROM GROSS=WAGE OF OUTPUT=MASTER 
GIVING TAXABLE*INCOME ROUNDED, 
IF MARRITAL@STATUS OF OUTPUT@MASTER 3 "MF 
GO TO MARRIED, 


Figure 5-20 (Cont.) 
Example of Using SEARCH 
To Search a Table 








CHAPTER 6 


FILE HANDLING 


PDP-11 COBOL provides three ways to arrange the records in its files 
(file organization): sequential, relative, and indexed. The 
ORGANIZATION in the Environment Division clause specifies the file 
organization for COBOL files. 


Indexed file organization is available 
only to users with RMS-11K software. 


PDP-11 COBOL provides three ways to process the records in its files 


(file access): sequential, random, and dynamic. The ACCESS MODE 
clause specifies the file access mode for each file used by COBOL 
programs. The following chart shows the three file organizations and 


the file access methods that apply to each of them: 


SEQUENTIAL SEQUENTIAL 


SEQUENTIAL 


FILE ACCESS 



















RELATIVE RANDOM 


DYNAMIC 







SEQUENTIAL 







INDEXED RANDOM 





DYNAMIC 





Once a program creates a file, all other programs that access it must 
describe it with the same file organization. For example, it is not 
possible to create a sequential file in one program and read it as a 
relative file with another. program. However, programS can _ use 
different access methods to process records in the same file as long 
as the organization of the file supports the access method. 
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The following table compares the different file organizations with 
their file manipulation capabilities. 


Table 6-1 
COBOL File Types 


Capabilities Sequential Relative Indexed 
Sequential Yes Yes Yes 
Random No Yes Yes 
Record 

Replacement Limited Yes Yes 
Record 

Addition (at end of file) Yes Yes Yes 
Record 

Insertion No Limited Yes 
Record 

Deletion No Yes Yes 


COBOL I/O statements allow COBOL programs to communicate with the 
system devices. These statements differ for sequential, relative, and 
indexed file organizations. Therefore, the COBOL I/O statements are 
discussed separately by file organization. Section 6.1 discusses 
sequential organization, Section 6.2 discusses relative organization, 
and Section 6.3 discusses indexed organization. All file processing 
is performed by the COBOL object time system (OTS), regardless of 
organization. 


Table 6-2 shows which statements apply to each file organization 
methods: 


Table 6-2 
I/O Statements 





Sequential I/O Statements Relative and Indexed I/O Statements 
| CLOSE | CLOSE | 
| OPEN | DELETE | 
| READ | OPEN | 
| REWRITE | READ | 
| WRITE REWRITE | 
| START | 
WRITE 
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6.1 SEQUENTIAL FILE ORGANIZATION 


Sequential file organization arranges the records in a file serially; 
each record (except the first) has another record preceding it and 
each record (except the last) has another record following it. The 
records remain in the order in which they were written. Thus, COBOL 
Statements cannot delete records from the file, insert new records 
between existing records, or alter the order of the existing records 
in any way. However, they can replace existing records (providing the 
length of the replacement record is identical to the original) and add 
new records onto the end of the file. 


The opening operation for reading, writing, or updating sequential 
files must begin with the first record in the file and proceed by the 
prescribed order through the file. For example, to read a particular 
record in the file, say the 15th record, the program must open the 
file and successfully execute 14 READ statements before the 15th 
execution can read the desired record. The program can read all of 
the remaining records (from record 16 on), but it cannot read any 
record prior to record 16 without opening the file again and beginning 
with record 1. 


Sequential files always contain an end-of-file mark that designates 
the end of the file. COBOL statements can write over the end-cf-file 
mark and, thus, extend the length of a file. (The software inserts 
another end-of-file mark after the last record written.) Since the 
end-of-file mark indicates the end of useful data, PDP-11 COBOL 
provides no method for reading beyond the end-of-file mark; even 
though the amount of space reserved for the file exceeds the amount 
actually used. See Figure 6-1. 


S| see [rec [rec | nec | we | neo | WY MMs 


: Se eee 
End-of-File Mark Unused Portion of Medium 
Reserved for File 





Figure 6-1 Placement of End-of-File Mark 


Occasionally a file with sequential organization is so large that it 
requires more than one volume (such as a multi-reel magnetic tape 
file). An end-of-volume label marks the end of recorded information 
on each volume and signals the file system to switch to a new volume. 
On multi-volume files, the end-of-file mark appears once, at the _ end 
of the last record on the last volume. See Figure 6-2. 


NOTE 


RSTS/E does not support multi-volume 
files. 
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End-of-Volume 


vou. 1 {REC [REC [REC } [REC [REC [ RECT} Label 


End-of-Volume 


vou. 2 {REC [REC [REC } [REC] REC RECT} Label 
VOL. 3 ¢ REC [ REC | REC pe REC | V7 


End-of-File Mark 


Figure 6-2 Placement of the End-of-Volume Label and 
End-of-File Mark in a Multi-Volume File 


Geta d. “RECORD: SIZE 


If there is only one record description for a file or if there are 
more than one that describe the same length record, that file contains 
fixed-length recorcs. If the data descriptions for a sequential file 
consist of more than one record description, which describe several 
different-sized records, that file contains variable-length records. 


When a program creates a sequential file with variable-length records, 
the software places a count field in front of each record it writes 
into the file. This count field contains the number of character 
positions in the record. When a COBOL statement requests the record, 
the software releases a record whose length is that specified by the 
count field. The OTS creates and uses the count field automatically. 
COBOL statements cannot access it during input operations, and the @1 
level record description entries must not describe it. 





Count fields 
6.1.2 RECORD CONTAINS Clause 


The RECORD CONTAINS clause, when specified without the "integer-1 TO" 
option, is for documentation purposes only. The compiler determines 
record size from the data descriptions. When the "“integer-1 TO" 
option is specified, it forces the compiler to generate a variable 
length record file, even if the data descriptions describe fixed 
length records. 


Conversely, if the data descriptions for a sequential file describe 
variable-length records, the software sets up variable sized records 
automatically and ignores this clause. 


Even though the software ignores the values in the "integer-1j TO..." 


phrase, the clause may be used in any program to document record 
sizes. 
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6.1.3 SAME RECORD AREA Clause 


The file system reserves a record processing area in memory for each 
file. This area is the current record area. The system fixes the 
location of the current record area when it opens the file. It also 
reserves a byte preceding and following each current record area for 
possible print-control characters. The current record area always 
begins on an even byte boundary. Two or more files may share a 
current record area if a SAME RECORD AREA clause contains their 
file-names. This clause causes the system to begin the current record 
area of each file listed at a common location. (Thus, current’ record 
areas that share space are aligned on their leftmost bytes.) The 
records do not have to be the same size and the current record areas 
need not have the same maximum size. The following sample statement 
would cause FILEA and FILEB to share the same current record area: 


I-O-CONTROL. 


SAME RECORD AREA FOR FILEA FILEB 


ince the system places a file's current record area in ae separate 
ocation from its buffers, each READ, WRITE, and REWRITE operation 
causes a record to move between the buffers and the current’ record 
area. When a program reads a record from a file, modifies it, and 
writes it into another file, a SAME RECORD AREA clause, containing 
both file-names, can save an entire move of the record. The following 
illustration shows these record movements: 


WITHOUT SHARING A CURRENT RECORD AREA 


READ WRITE 







FILEA FILEB 
Buffer Buffer 
FILEA FILEB 
Current Current 
Record Record 
Area Area 


SHARING A CURRENT RECORD AREA 


FILEB 
Buffer Buffer 


FILEA & FILEB 
Current Record Area 





Record Movement Caused by 
Reading, Processing, and Writing 
Records in Two Files 
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6.1.4 PRINT-CONTROLLED RECORDS 


If a sequential file is described in a LINAGE IS clause, an APPLY 
PRINT-CONTROL clause, or is referenced in a WRITE statement with the 
ADVANCING clause specified, and the file is not going directly to a 
printing device (is going to be spooled), the software designates the 
file as a print-controlled file. Print-controlled files contain form 
advancing information with each record. Explicit forms control bytes 
are placed directly into the file. Therefore, any COBOL program 
trying to process a print-controlled file may have unpredictable 


2 wre we ew “ bl a a an oe su y i ad oe Vee we 
results. 


6.1.5 RECORD BLOCKING 


The manner in which the file system blocks the records of sequential 
files depends on the device to which the file is assigned and the 
presence and format of the BLOCK CONTAINS clause. 


COBOL programs can assign sequential files to disk which requires 
fixed-length virtual blocks, and to magnetic tape, which allows 
variable-length blocks. 


The BLOCK CONTAINS clause of a COBOL program refers to a logical block 


size. For magnetic tape, the logical block size and virtual block 
size are the same. For disk, however, the logical block size is equal 
to one or more virtual blocks. (A virtual block on disk is 512 
bytes). 


For files assigned to disk, the OTS packs records together 
(end-to-end) until a logical block is filled. The logical block is 
written to disk, and any portion of the previously processed record 
that did not fit into the logical block is put into the next logical 
block. This process is called record spanning in that it allows 
records to span virtual block boundaries. 


Record spanning is prohibited for files assigned to magnetic tape. 
For these files, only complete records (fixed or variable length) are 
placed end-to-end in a logical block. The OTS writes the logical 
block out to the file when it determines that the block is full to the 
extent that the next record will not fit into it. 

There are three ways to specify block size in a COBOL program; by 
default; by uSing the BLOCK CONTAINS integer RECORDS clause; or by 
using the BLOCK CONTAINS integer CHARACTERS clause. The default 
philosophy is to make the logical block size as small as possible; 
thus minimizing the memory buffer space required. By using the BLOCK 
CONTAINS (integer RECORDS or integer CHARACTERS) clause, you can 
increase the memory buffer space required. Increasing the buffer 
space, allows for faster I/0 by decreasing the number of I/O 
operations required to process a file. Use the BLOCK CONTAINS clause 
only if you can afford the price of additional memory buffer space for 
the ability to process your files faster. Tne following paragraphs 
further define the three blocking methods: 


Default 


By default, the logical block size is made equal to the _ record 
size (add four bytes for variable length records on magnetic tape 
or two bytes for variable length records on disk). For disk 
files, the logical block size is rounded up to the next even 
multiple of 512 bytes to make the logical block size an integral 
number of virtual blocks. For example: 
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If the maximum record size for a disk file is 518 bytes, and the 
file contains variable length records, then the logical block 
size is 1824 bytes. (518 plus 4 for variable length reccrds is 
514, and 514 rounded up to the next even multiple of 512 is 
1024.) 


BLOCK CONTAINS integer RECORDS 


If this clause is used, the logical block size is equal to _ the 
record size (plus four bytes for variable length records on 
magnetic tape or two bytes for variable length records on _ disk) 
times the number of records per block. For disk files, the 
logical block size is rounded up to the next even multiple of 512 
bytes to make the block size an integral number of virtual 
blocks. For example: 


If the record size for a fixed-length disk file is 100 bytes and 
the clause BLOCK CONTAINS 1@ RECORDS is specified, the logical 
block size is 1@24 bytes. (10@ times 10 is 1000, and 1400 
rounded up to the next even multiple of 512 is 1@24). 


BLOCK CONTAINS integer CHARACTERS 


If this clause is used, the logical block size is equal to _ the 
number of characters given in the clause. If the specified 
number of characters is less than the actual record size (plus 
four bytes for variable-length records on magnetic tape or two 
bytes for variable length records on disk) the compiler generates 
a block size that is equal to the actual record size. For disk 
files, the specified number of characters must equal an even 
multiple of 512. If the number you specify is not correct, the 
OTS will round the logical block size it finds to the next even 
multiple of 512 bytes. 


When a program assigns a file to> magnetic tape, all programs’ that 
access the file must describe it the same way that the creating 
program described it in order to guarantee an accurate allocation of 
buffers. 


Note: The previous discussion has used the following format: 
RECORDS 
BLOCK CONTAINS integer 
CHARACTERS 


If the following format is used: 


RECORDS 
BLOCK CONTAINS [integer-1 TO Jinteger-2 
CHARACTERS 


the compiler ignores integer-1, and integer-? is used as the integer. 


6.1.6 BUFFERING 


When the system performs an input operation, it reads a block from the 
medium into the buffer, and moves a record from the buffer to the 
current record area. Each subsequent read operation moves a= record 
from the buffer to the current record area. When it has exhausted the 
buffer (has read an entire block), the system reads another block into 
the buffer. 
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When performing an output operation, each write operation moves a 
record from the file's current record area into the file's buffer. 
Each subsequent write operation moves a record from the current record 
area into the buffer. The system writes the block to the medium when 
it has filled the buffer. 


The following subsections discuss the size of the buffers, the number 
of buffers, and the sharing of buffers. 


6.1.6.1 Buffer Size - Buffer size depends on the size of the largest 
record in the file and on the blocking factor. For files with 
sequential organization, the buffer size will be at least 512 bytes. 


6.1.6.2 I-0O Buffer Areas - The RESERVE clause in the Environment 
Division specifies the number of I-O buffer areas to be allocated for 
each file. Each I-O area represents the space for one logical block. 
A minimum of one and amaximum of two are permitted for sequential 
files. One is the default. Since two I-O areas do not increase the 
speed of access and take additional memory space, it is recommended 
that this clause not be used. 


6.1.6.3 Buffer Space - To calculate the total amount of buffer space 
required for each sequential file, the following algorithm may be 
used: 


Buffer space = record size + (logical blocksize * no. of areas) 
+ 234 


In addition there are 76 bytes of buffer space that are shared among 
all files. 


6.1.6.4 Sharing Buffer Space Among Files - The SAME AREA clause 
provides a Simple method of sharing buffer space among several files. 
Two or more files may share the same buffers if the SAME AREA clause 
contains their file-names and only one of them is open at any time 
during program execution. Further, since only one file is open at a 
time, the files will also share the same current record area. The 
size of the current record area is set to the size of the largest 
record description specified in the group. 


If only one of these files is open at a time, the following sample 
statement causes them all to share the same buffer and current record 
area. 

I/O-CONTROL. 


SAME AREA FOR FILEA FILEB FILEC. 


coh) 
! 
(oe) 
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6.1.7 SEQUENTIAL I/O STATEMENTS 


PDP-11 COBOL provides the following I/0 statements for sequential 
files: 


e CLOSE 

e OPEN 

e READ 

e REWRITE 
e WRITE 


Before a COBOL program can access a file, it must open the file; 
then, when the program is finished with the file, it must close the 
file. 


A COBOL program may open a sequential file in one of four’ modes, 
INPUT, OUTPUT, I-O (input/output), or EXTEND. In INPUT mode, records 
may be read from the file; in OUTPUT mode the file is created and 
records can only be written to it; in I-O mode, records can be read 


from the file and updated; in EXTEND mode, records may be added onto 
the end of the file. Table 6-3 shows which statements apply to the 
four different OPEN modes of sequential files. (The table does not 


include the OPEN and CLOSE statements since they apply to all modes.) 


Table 6-3 
Sequential OPEN Modes 


Open Mode 
Statement Input Output Input-Output Extend 


REWRITE 





6.1.7.1 Opening Sequential Files - The OPEN statement makes a file 
available for processing by a COBOL program. A program must execute 
an OPEN statement for a file before it executes any other I/0 
statement for that file. Consider the following sample OPEN 
statement. It opens the file named THOREAU for input/output. The 
program containing this statement could, after executing it, READ, 
REWRITE, and CLOSE THOREAU. 
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ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT THOREAU 
ASSIGN TO "DK1:". 


DATA DIVISION. 


FILE SECTION. 
FD THOREAU 


PROCEDURE DIVISION. 


OPEN I-O THOREAU. 


The OPEN statement must refer to the file by the file-name appearing 
in both the SELECT clause in the Environment Division and the FD 
paragraph in the Data Division. 


When the OTS executes an OPEN statement, it performs the following 
actions for the file named in the statement: 


If the file is already open, the OTS generates an error 
message and performs the USE procedure section (if 
specified). (Section 6.8 discusses USE procedures and 
Section 12.3 discusses error messages.) 


When opening an existing file, the attributes (i.e., record 
length, block size, etc.) of the file are used for accessing 
the file. Those specified in the program are ignored. Be 
sure that the attributes specified in the COBOL program agree 
with the actual attributes of the file. 


If the SELECT clause of the File-Control paragraph declares 
the file OPTIONAL, the OTS displays the following message: 


"FILE nnn ... OPTIONAL FILE MOUNTED? Y OR N?" 
(nnn represents the file-name.) 


If the file is available for processing, type a Y. If not, 
type an N. If the file is not available (N), the OTS 
disables all I/O processing on the file except READ an 

CLOSE; a later READ statement causes program control to take 
the AT END imperative path. 


If a SAME AREA clause contains the name of the file and none 
of the other files named in the clause is open, the OTS 
allocates buffer space for the file. 


When the file has passed all of the preceding checks and is 
ready for opening, the OTS instructs the Record Management 
Services to open the file. If the Record Management Services 
fails to open the file, the OTS reports an error condition 
and performs any applicable USE procedure (if present). 
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° If the program is creating the file (OPEN OUTPUT) and the 
file description specifies LINAGE or APPLY PRINT-CONTROL, the 
OTS initializes the LINAGE counters. 


e Finally, depending on which statements apply to the open 
mode, the OTS enables or disables all of the program's I/0 
statements that refer to the file (see Table 6-3). For 
example, if the OPEN mode is INPUT, it enables all READ 
Statements for that file and disables all REWRITE and WRITE 
statements for that file. 


Since the EXTEND mode simply allows the WRITE statement to add records 
onto the end of the file, files opened in this mode must already exist 
on disk or tape (only the last file on magnetic tape can be extended). 
If the file does not exist, the OPEN statement fails and the OTS 
issues an error message. 


6.1.7.2 Reading Sequential Files - The READ statement makes the next 
logical record of an open sequential file available to the program. 
If the preceding I/O operation was an OPEN, it makes the first record 
of the file available to the program. 


Consider the following example. If the last I/O operation on the file 
named THOREAU was an OPEN, this statement would provide the program 
with the first record in the file THOREAU. Every time the statement 
is executed, it provides the program with the next sequential record 
in THOREAU. Program control transfers to the paragraph named LIBRARY 
when an end-of-file mark is encountered during the READ. 


BEGIN. OPEN THOREAU. 
LOOP. READ THOREAU AT END GO TO LIBRARY. 


GO TO LOOP. 


If the file contains variable-length records, the program must 
determine the length of the record just read. No such information is 
Supplied to the user program. 


NOTE 


RSTS/E processes records from unit 
record devices as variable length 
records. This means that records’ read 
in from a card reader or paper tape 
reader will have trailing blanks 
deleted. For example, reading blank 
records will not change the user’ record 
area. To avoid problems, move blanks 
into the record area before each read. 


If the file is open in the I-O mode, the successful execution of a 
READ statement enables any following REWRITE of the record just read. 
(For further information on the REWRITE statement, see the next 
subsection -- 6.1.7.3.) 
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If the file has more than one record description, the records 
automatically share the same current record area. The OTS does not 
clear this area before it executes the READ statement (no blank 
filling, ete.). Therefore, if the record read by the latest READ 
statement does not fill the entire current record area, the area not 
overlaid by the incoming record remains unchanged. For example, if 
the file's record area contains ten 3's, and a READ operation moves in 
a 6-character record containing all 1's, the current record area then 


contains six 1's followed by four 3's. Consider the following 
example: 

Current Record Area with all 3's 33333333535 

Next Record in the File 117111 

Current Record Area after READ 


6.1.7.3 Rewriting Records into sequential Files - The REWRITE 
statement places the record just read from an input-output file back 


into its file on disk or magnetic tape. (The WRITE statement cannot 
access I-O files.) The following sample statement writes the record, 
REC1, back into its file. (REC1, of course, must be a record in the 
file read by the preceding READ for that file.) 


REWRITE REC1 


Before the REWRITE statement can refer to ae record, the program 
containing the statement must meet the following conditions: 


e The file containing the record must be open in the I-0O mode; 


e The last I/O operation on the file containing the record must 
have been a successful READ; 


e The record length of the record to be rewritten must be the 
same as the record last read from the file. 


6.1.7.4 Writing Sequential Files - The WRITE statement releases a 
logical record to an output file, thereby creating an entirely new 
record in the file. 


The following sample WRITE statement releases the record PRINT-LINE to 
the device assigned to that record's file, then skips three lines. 
When it reaches the end of a page (as specified by the LINAGE clause), 
it causes program control to transfer to the subroutine, HEADER-RTN. 


= AS 


Note that this produces two blank lines following every line printed. 


The WRITE statement releases records to files that are open in either 
the output or extend mode. The following text discusses the two modes 
separately. 


e OUTPUT Mode - The WRITE statement can create the following 
two kinds of files in the OUTPUT mode: 
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1. Print-files - A print-file produces a listing on a 
printing device. The LINAGE clause, the APPLY 
PRINT-CONTROL clause, or a WRITE statement with the 
ADVANCING option included, designates a file as a 
print-file. One or more records containing 
carriage-control characters are written to perform line 
spacing. The WRITE statement does not have to release 
print-files directly to a printing device, but may also 
release them to a storage medium such as disk for 
printing at a later time. 


2. Storage files - A storage file remains on disk or tape 
for future reference. All files that are not print-files 
are storage files. A sample storage file WRITE statement 
follows; this statement writes a record named WALDEN 
into a file: 


WRITE WALDEN 


e EXTEND Mode - A WRITE to a storage file opened in the EXTEND 
mode simply adds new records logically in sequence after the 
last record in the fiie. As tne Statement extends tne file, 
the Record Management Services automatically handles requests 
for additional storage space. (Print-files on disk should 
only be opened for EXTEND if they are being opened as a 
print-file.) 


6.1.7.5 Closing Sequential Files - The CLOSE statement terminates 
processing on the file referred to in the statement. The following 


sample CLOSE statement terminates processing on the file named 
THOREAU: 


CLOSE THOREAU 


When the CLOSE statement closes a file, no other I/0 operation can 
access that file until another OPEN statement opens the file. 


If the statement specifies the LOCK option, the program cannot open 
the file again in this run. The CLOSE statement with the LOCK clause 
is shown below: 


CLOSE THOREAU WITH LOCK 


The lock option has no effect on the physical device containing the 
file. 


If a SAME AREA clause contains the name of the file just closed, the 
program may open one of the other files named in the clause. 


6.2 RELATIVE FILE ORGANIZATION 


Relative file organization arranges the records of the file into 
numbered record positions. It assigns each record position a number 
that identifies that position relative to the beginning of the file 
(the first record position in the file has record number 1, the second 
has record number 2, etc.). 
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Record Positions in a Relative File 


When a program executes a random DELETE, REWRITE, READ or WRITE 
operation on a relative file, the value in the relative key is used to 
select records from these numbered record positions in the Same way 
that a subscript selects an item in a table. 


Thus, while sequential and relative files both arrange their record 
positions in a serial order, COBOL statements can address the record 
positions of a relative file by their position numbers, and successive 
accesses do not have to proceed through the file in a prescribed, 
serial, order. 


Another significant feature of relative file organization is that each 
record position does not have to contain a valid record. Although 
each position actually occupies one record space, a byte preceding the 
record on the storage medium indicates whether or not that space 
contains a valid record. Thus, a file may have fewer records than it 
has record positions, and the indicated empty record positions may be 
anywhere in the file. 


The numerical order of the record positions remains the same during 
all operations on a relative file; however, the accessing statements 
can move a record from one position to another, delete a record from a 
position, or insert new records into empty positions. 


Ge2e1 RECORD: SIZE 


A relative file may contain either fixed-length or variable-length 
records. (Fixed-length records have one or more record descriptions 
that describe the same size record. Variable-length records have more 
than one record description that describe several different sized 
records.) However, the COBOL compiler allocates a record area on the 
I/O device, equal to the largest record described plus one. This 
extra byte is an existence byte. It indicates whether the record area 
contains a valid record. For variable length records in a relative 
file, the software adds a two byte count field. On awrite operation 
the actual record is written out to the I/0 device not the maximum 
length record. The length of this record is placed in the two byte 
count field. On a read operation this two byte count field is used to 
determine the length of the record to be read in. 


6.2.2 RECORD CONTAINS Clause 


The RECORD CONTAINS clause, when specified without the "integer-1 TO" 
option, is for documentation purposes only. The compiler determines 
record size from the data descriptions. When the "“integer-1 TO" 
option is specified, it forces the compiler to generate a variable 
length record file, even if the data descriptions describe fixed 
length records. 


Conversely, if the data descriptions for a sequential file describe 
variable-length records, the software sets up variabie sized records 
autometically and ignores this clause. 


Even though the software ignores the values in the "integer-1i TO..." 
phrase, the clause may be used in any program to document record 


Sizes. 
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6.2.3 SAME RECORD AREA Clause 


The SAME RECORD AREA clause is identical for all file organizations. 
See Section 6.1.3. 


6.2.4 RECORD BLOCKING 


The size of a file is expressed aS an integral number of virtual 
blocks. Virtual blocks are physical storage structures. That is, 
each virtual block within a file is a unit of data whose size depends 
on the physical medium on which the file resides. 


Relative files may reside only on disk. The size of virtual blocks 
within files on disk devices is always 512 bytes. 


Relative files use a logical storage structure known as a logical 
block or bucket. A bucket consists of from 1 to 32 virtual blocks. 


This distinction should be made clear. A virtual block is a physical 
entity which is fixed in size and cannot be changed. A bucket, 
nowever, iS a logical entity. Its size is directiy under your 
control. Records may span virtual block boundaries. They may never 
Span bucket boundaries. 


Increasing the bucket size increases the _ speed of sequential 
processing of a file because fewer I/O operations are needed to access 
the smaller number of buckets in the file. On the other hand, a 
larger bucket size means that more memory space is taken up by the I/0 
buffers. Increasing the bucket size may not increase the speed of 


: : F 
random processing of a relative file. 


There are three ways that the bucket size may be specified in a COBOL 
program; by default, by using the construct BLOCK CONTAINS integer 
RECORDS, or by using the construct BLOCK CONTAINS integer CHARACTERS. 


The default is to make the bucket size as small as possible, to 
minimize the memory buffer space required. By using the BLOCK 
CONTAINS integer (RECORDS of integer CHARACTERS) clause, you can 
increase the memory buffer space required. Increasing the buffer 
Space allows for faster I/0 by decreasing the number of operations 
required to access a file. The following paragraphs further define 
the three blocking methods: 


Default 

The default philosophy is to make the bucket size as small as 
possible to minimize the memory buffer space required. The 
algorithms for calculating the bucket size follow: 


Bnum= ((1+Rlen)/512)+1 Fixed length record 


Bnum= ((3+Rmax)/512)+1 Variable length record 


Where: 
Bnum is the number of virtual blocks per bucket. 
Rlen is the fixed record length (in bytes). 
Rmax is the maximum record length (in bytes) if the 


record length is variable. 
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existence byte plus 2 bytes for the record length. 


Table 6-4 gives the bucket size for record lengths. 


Table 6-4 


Bucket Sizes for Record Lengths 


Ee a ee ee i 


1-511 

512-1823 
1024-1535 
1536-2047 
2048-2559 
2560-3071 
38072-3583 
3584-4895 


1-589 

510-1021 
1822-1533 
1534-2845 
2046-2557 
2558-3069 
3076-3581 
3582-4093 


The number 3 is for’ the 


1 
2 
3 
m 
e. 
6 
7 
8 
e 





BLOCK CONTAINS Rnum RECORDS 
If the BLOCK CONTAINS Rnum RECORDS clause is used, where Rnum is 
an integer, then the following algorithms are used to calculate 
the bucket size. 

Bnum= (((Rlen+1)*Rnum)/512)4+1 Fixed length record 


or 


Bnum= (((Rmax+3)*Rnum)/512)+1 Variable length record 


Where: 
Bnum is the number of virtual blocks per’ bucket, 
ranging from 1 to 32. 
Rlen is the fixed record length (in bytes). 
Rmax is the maximum record length (in bytes) if the 
record length is variable. 
Rnum is the number of records per bucket as given in 


the BLOCK CONTAINS clause. 


BLOCK CONTAINS Cnum CHARACTERS 


If the BLOCK CONTAINS Cnum CHARACTERS clause is used, where Cnum 
is an integer, then Cnum is subject to the following constraints. 
(1) Cnum = Rlen+1 for fixed length records 
or 
Cnum Rmax+3 for variable length records 


(2) Cnum mod 512 = @ 
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Based on CNUM, the bucket size is calculated as follows: 


Bnum=Cnum/512 


where: 
Cnum is the number of characters per bucket as given in 
the BLOCK CONTAINS clause. 
Rlen is the fixed record length (in bytes). 
Rmax is the maximum record length (in bytes) if the 
record length is variable. 
Bnum is the number of virtual blocks per bucket, 


ranging from 1 to 32. 


Violation of constraint (1) causes a warning error and the 
default method is used to calculate the bucket size. Constraint 
(2) means that Cnum should be a muitiplie of 5i2. If not, a 
warning error is given and Cnum is increased to the next even 


multinila of 5193 

wwe Ve aw we wy7~ i'ia-¢@ 

The bucket size must be the same when the file is created and 
each time the file is accessed. Therefore, the BLOCK CONTAINS 
clause must never change for a particular file. 

Note: The previous discussion has used the following format: 


|  eulaelae 
| BROCE CONTAINS integer 


( CHARACTERS 





If the following format is used: 


RECORDS 
BLOCK CONTAINS[integer-1 TO ]integer-2 
CHARACTERS 
the compiler ignores integer-1, and integer-2 is used as_ the 
integer. 


6.2.5 BUFFERING 


When the system performs a sequential or random input operation, it 
reads a bucket from the medium into the buffer, and moves a record 
from the buffer to the current record area. Any subsequent sequential 
read operations move a record from the buffer to the current record 
area. When it has exhausted the buffer (has read an entire bucket), 
the system reads another bucket into the buffer. 


When performing a random read operation, the appropriate bucket is 
read into a file's buffer. The record is then moved from the buffer 
to the current record area. 


When performing a sequential output operation, each write operation 
moves a record from the file's current record area into the file's 
buffer. Each subsequent sequential write operation: moves a. record 
from the current record area into the buffer. The system writes the 
bucket to the medium when it has filled the buffer. 
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When performing a random output operation, the appropriate bucket is 
read and the record is moved from the file's current record area into 
the appropriate position in the file's buffer. The system writes the 
bucket back out to the medium before reading any additional blocks. 


The following subsections discuss the size of the buffers, the number 
of buffers, and the sharing of buffers. 


6.2.5.1 Buffer Size - Buffer size depends on the size of the largest 
record in the file and on the blocking factor. For relative files, 
buffer size must be some multiple of 256 words (512 bytes). 


6.2.5.2 I/0 Buffer Areas - The RESERVE clause in the Environment 
Division specifies the number of I/O buffer areas to be allocated for 
each file where an area represents the space for one bucket. A 
minimum of one and a maximum of two I/O areas are permitted for 
relative files. One is the default. It is recommended that this 
clause not be used, because two I/O areas do not increase the speed of 
access and take up additional space. 


6.2.5.3 Buffer Space - To calculate the total amount of buffer space 
in bytes required for each Relative file, the following algorithm may 
be used: 


Buffer space = record size + bucket size + 266 


In addition, there are 76 bytes of buffer space that are shared among 
all files. 


6.2.5.4 Sharing Buffer Space Among Files - The SAME AREA clause 
provides a simple method of sharing buffer space among several files. 


This clause is identical for all file organizations. See Section 
6.1.6.4. 


6.2.6 RELATIVE 1/0 STATEMENTS 


The COBOL I/O statements, CLOSE, DELETE, OPEN, READ, WRITE, REWRITE, 
and START can refer to relative files. 


A COBOL program may open a relative file in one of three modes, INPUT, 
OUTPUT, or I-O, and access an open relative file in one of three ways, 
sequentially, randomly, or dynamically. In INPUT mode, records may be 
read from the file; in OUTPUT mode, the file is created and records 
may be written to the file; in I-O mode, records may be read from the 
file, updated on the file, deleted from the file, or written to the 
file. The following table shows which statements and access methods 
apply to the three different OPEN modes of relative files. 
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Table 6-5 
Relative OPEN Modes 


FILE ACCESS QPEN MODE 
MODE STATEMENT 


DELETE 
READ 
Sequential REWRITE 


START 
WRITE 


DELETE 

READ 
Random REWRITE 

START 


WRITE X X 








| | DELETE | | | 
| READ | x | | 
| Dynamic READ NEXT | X | 
REWRITE 
START 
WRITE 





Ps PS PS PS PS PS 


NOTE 


The term, current record pointer, used 
in the following sections, refers to a 
location in the operating system used to 
determine the record number of the next 
available record in a file. 


6.2.6.1 Access Modes - The ACCESS MODE clause in the File-Control 
paragraph dictates which of the three access modes may be used on that 
file. 


When the ACCESS MODE clause specifies SEQUENTIAL, the I/0 statements 
must refer to the records in the file sequentially, starting (after 
opening) with the first record and stepping through with each 
reference to the end of the file. The I/O statements ignore record 
positions that do not contain valid records. 


When the ACCESS MODE clause specifies RANDOM, the I/O statements refer 
to the records in the file by record position. Thus, the statements 
may refer to record positions that do not contain valid records. The 
program must specify the desired record position number by placing a 
value in the file's relative key. If an I/O statement refers to a 
record position with the relative key, and that record position does 
not exist (either because the position does not contain a record or 
because it is beyond the end of the file), the INVALID KEY imperative 
statement may be executed depending on the particular I/0 statement 
used. (The INVALID KEY imperative statement is explained with each of 
the relative I/O statements in this section.) 
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When the ACCESS MODE clause specifies DYNAMIC, the I/O statements may 
refer to the records in the file either sequentially or randomly. The 
OTS determines which access method to use from the OPEN mode (INPUT, 
OUTPUT, or I-0) and the form of the I/O statement. For example, if 
the statement READ ...INVALID KEY is to access an open input file 
dynamically, the OTS uses the relative key for random access; if the 
statement READ NEXT ... is to access an open input file dynamically, 
the OTS sequentially accesses the next existing record. 

The following sections (6.2.5.2 through 6.2.5.8) on using t 
statements themselves contain additional information about 
modes. 


e 1/0 
access 


a 


6.2.6.2 Opening Relative Files - The OPEN statement for a= relative 
file makes an INPUT, OUTPUT, or I-O mode file available so the COBOL 
program can access the records in the file sequentially, randomly, or 
dynamically. 


The OPEN statement sets the current record pointer for the file to 
zero. 


For example, the following sample OPEN statement opens the file named 
ARTICHOKE for input, and sets ARTICHOKE's current record pointer to 
zero. The program containing this statement could, after executing 
the statement, access ARTICHOKE with READ and START statements in the 
sequential access mode, READ statements in the random access mode, or 
READ, READ NEXT, and START statements in the dynamic access mode. 


OPEN INPUT ARTICHOKE. 


When the OTS executes an OPEN statement, it performs the following 
actions for the file named in the statement: 


e If the file is already open, the OTS generates an error 
message and performs the USE procedure section (if 
specified). (Section 6.8 discusses USE procedures and 
Section 12.3 discusses error messages.) 


e When opening an existing file, the attributes (i.e., record 
length, block size, etc.) of the file are used for accessing 
the file. Those specified in the program are ignored. Be 
sure that the attributes specified in the COBOL program agree 
with the actual attributes of the file. 


e If a SAME AREA clause contains the name of the file and none 
of the other files named in the clause is open, the OTS 
allocates buffers space for the file. 


When the file has passed all of the preceding checks and is 
ready for opening, the OTS instructs the Record Management 
Services to open the file. If the Record Management Services 
fails to open the file, the OTS reports an error condition 
and performs any applicable USE procedure (if present). 


e Finally, depending on which statements apply to the open 
mode, the OTS enables or disables all of the program's I/0 
statements that refer to the file (see Table 6-5). For 
example, if the OPEN mode is INPUT, it enables all READ and 
START statements for that file .and disables aii REWRITE, 
DELETE and WRITE statements for that file. 
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If the file is being accessed randomly or dynamically, the program 
must maintain a correct value in the relative key. If the file is 
being accessed sequentially, the OTS ignores the value of the relative 
key, but updates it to contain the position number of the record being 
accessed. 


6.2.6.3 Reading Relative Files - When applied to a file being 
accessed sequentially, the READ statement makes the next logical 
record of an open file available to the program. 


When applied to a file being accessed randomly, the READ statement 
selects a specified record from an open file and makes it available to 
the program. The value of the relative key for the file identifies 
the specific record. 


When applied to a file being accessed dynamically, the READ statement 
has two formats so that it can either select the next logical record 
(sequentially) or select a specified record (randomly) and make it 
available to the program. The READ NEXT statement takes the number in 
the current record pointer and finds the next present’ record. The 
following sample READ statement reads the file named ARTICHOKE 
sequentially and, when it exhausts the file, causes program control to 


transfer to the subroutine named FILEOUT: 


READ ARTICHOKE NEXT RECORD 
AT END GO TO FILEOUT. 


For further information concerning the mechanics of the READ NEXT 
Statement, see Section 6.2.5.7, Specifying the Next Record to be Read. 


The READ with key takes the value in the relative key, moves it to the 
current record pointer, and reads the record being pointed to. The 
following READ (with key) statement reads the file named ARTICHOKE 
randomly, selecting records through the value in the file's relative 
key. If the relative key supplies a value that does not contain a 
valid record, the statement causes program control to transfer to the 
Subroutine named NO-REC. 


READ ARTICHOKE RECORD 
INVALID KEY GO TO. NO-REC. 


If the file has more than one record description, the records 
automatically share the same current record area. The OTS does not 
clear this area before it executes the READ statement (no blank 
filling’, “etas). Therefore, if the record read by the latest READ 
statement does not fill the entire current record area, the area not 
overlaid by the incoming record remains. unchanged. For example, if 
the file's record area contains ten 3's, and a READ operation moves in 
a 6-character record containing all 1's, the current record area then: 


contains six 1's followed by four 3's. Consider the following 
example: 

Current Record Area with all 3's 3353553555 

Next Record in the File 111111 


Current record Area after READ 1111113333 
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6.2.6.4 Rewriting Records into a Relative File - The REWRITE 
statement places a record back into its file on disk or magnetic tape. 
The following sample statement writes the record, BREAKERS, back into 
its file. 


REWRITE BREAKERS. 


If the file is open in the sequential access mode, the statement 
rewrites the record just successfully read. If the file is open in 
either the random or dynamic access mode, the statement rewrites the 
record to the record position specified by the relative key. 


6.2.6.5 Writing Records in a Relative File - The WRITE statement 
releases a logical record to a file. The following sample WRITE 
statement releases the record BREAKERS to the device assigned to that 
record's file. If the record already exists, program control 
transfers to the subroutine, WRITE-ERR. 


WRITE BREAKERS 
INVALID KEY GO TO WRITE-ERR. 


The WRITE statement releases records to files that are open in either 
the OUTPUT or I/O mode. The following text discusses the two modes 
separately: 


e OUTPUT Mode - The WRITE statement's only function with output 
files is to place entirely new records into the file. If 
more space is required for new record positions, the Record 
Management Services automatically extends the file size, 
regardless of the access mode being employed. 


e I/O Mode - The statement's function with input-output files 
is to place records in record positions that already exist 
and are empty. The length of the records must not exceed the 
maximum length record specified for the file when it was 
created. 


The relative WRITE statement creates only storage files since 
print-files are sequential files. The following SAMPLE statement 
writes a record named BREAKERS into its file: 


6.2.6.6 Deleting Records from a Relative File - The DELETE statement 
logically removes an existing record from a relative file. After a 


DELETE statement has successfully removed a record from a file, that 
record can no longer be accessed. 


If the file is open in the sequential access mode, the statement 
removes the record just successfully read. For example, the following 
Sample statement removes the record just read from the file named 


MTOUAYW IT « 


DELETE ARTICHOKE RECORD. 
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If the file is open in either the random or dynamic accéss mode, the 
statement removes the record from the record position specified by the 
relative key. For example, the following sample statement deletes the 
record specified by the relative key from the file named ARTICHOKE; 
if the relative key supplies a value that does not contain a valid 
record, the statement transfers control to the subroutine named 
NO-REC. 


DELETE ARTICHOKE RECORD 
INVALID KEY GO TO NO-REC. 


6.2.6.7 Specifying the Next Record to be Read = The START statement 
specifies which record in a file will be the next one to be referenced 


sequentially. 


A READ NEXT statement should follow the START statement since the READ 
NEXT statement reads the next record from the one being pointed to by 
the current record pointer. 


If the data area, SOMETHING, in the following example contains a 34 
and position 33 in the file contains the next present record, the 
START statement sets the current record pointer to one less than 33 
(32). The READ NEXT statement would then find the next present 


record, which we know is 33. 


WORKING-STORAGE SECTION. 
77 SOMETHING PIC S99 VALUE 3@. 
77 ARTKEY PIC 99. 


RD-SET. MOVE SOMETHING TO ARTKEY. 
START ARTICHOKE 
KEY IS GREATER THAN ARTKEY 
INVALID KEY GO TO NEWKEY. 


IN1. READ ARTICHOKE NEXT RECORD 
AT END GO TO FILEOUT. 


The value of the RELATIVE KEY data item specified in the statement 
(ARTKEY in the preceding example) together with the conditional phrase 
specified in the statement (IS GREATER THAN in the preceding example) 
determines which record in the file will be accessed by the READ NEXT 
statement. 


The START statement uses the value in the RELATIVE KEY data item to 
set the current record pointer. If record positions 3@ and 33 contain 
valid records and ARTKEY contains 38, the START statement would set 
the current record pointer and RELATIVE KEY data item as follows: 


1. If the conditional phrase specifies KEY IS GREATER THAN 
ARTKEY, the statement sets the current record pointer to 32. 


2. If the conditional phrase specifies KEY IS EQUAL TO ARTKEY or 
NOT LESS THAN ARTKEY, the statement sets the current record 
pointer to 29. 


The READ NEXT statement takes the number in the current record pointer 
and finds the next present record from that number. (If the pointer 
contains a 3@ and the next present record is in position 33, it finds 
record number 33). The READ NEXT statement gets that record and 
places its record position number (33) into the current record pointer 
and the relative key. 
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A subsequent READ NEXT takes the number in the current record pointer, 
which is now 33 in our example, and finds the next present record. It 
fetches that record and places its record position number in the 
current record pointer and relative key. 


6.2.6.8 Closing Relative Files - The CLOSE statement terminates 
processing on the file referred to in the statement. The following 
sample CLOSE statement terminates processing on the file named 
ARTICHOKE: 


CLOSE ARTICHOKE. 


When the statement closes a file, no other I/O operation can access 
that file until another OPEN statement opens the file. 


If the statement specifies the LOCK option, the program cannot open 
the file again in that run. 


If a SAME AREA clause contains the name of the file just closed, the 
program may open one of the other files named in the clause. 


6.3 INDEXED FILE ORGANIZATION 


WARNING 


Indexed file organization is available 
only to users having RMS-11K software. 


Unlike the physical ordering of records in a sequential file or the 
relative positioning of records in a relative file, the location of 
records in the indexed file organization is transparent to your 
program. The presence of keys in the records of the file governs the 
placement of records in an indexed file. 


A key is a character string present in every record of an indexed 
file. The location and length of this character string is identical 
in all records. When creating an indexed file, you decide which 
character string in the file's records is to be a key. By selecting 
such a character string, the contents (i.e., key value) of that string 
in any particular record written to the file can be used by a program 
to identify that record for subsequent retrieval. 


You must define at least one key for an indexed file. This mandatory 
key is the primary key of the file. Optionally, you can define up to 
255 additional keys (i.e., alternate keys). Each alternate key 
represents an additional character string in records of the file. The 
key value in any one of these additional strings can also be used as a 
means of identifying the record for retrieval. 


As programs write records into an indexed file, the values contained 
in the primary and alternate keys are used to locate the record in the 
file. From the values in keys within records a tree-structured table 
known as an index is built. An index consists of a series of entries. 
Each entry contains a key value copied from a record that a= program 
wrote-into the file. With each key value is a pointer to the location 


in the file of the record from which the value was copied. A separate 
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index is built and maintained for each key you define for the file. 
Each index is stored in the file. Thus, every indexed file contains 
at least one index, the primary key index. When you define alternate 
keys, an additional index is built and maintained for each alternate 
key. Figure 6-3 shows the general structure of an indexed file that 
has been defined with only a single key. Figure 6-4 depicts an 


indexed file defined with two keys, a primary key and one alternate 
key. 
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6.3.1 RECORD SIZE 


A relative file may contain either fixed-length or variable-length 
records. (Fixed-length records have one or more record descriptions 
that describe the same size record. Variable-length records have more 
than one record description that describe several different sized 
records.) For variable length records in an indexed file, the software 
adds a two byte count field. On a write operation the actual record 
is written out to the I/0 device not the maximum length record. The 
length of this record is placed in the two byte count field. On a 
read operation this two byte count field is used to determine the 
length of the record to be read in. 


6.3.2 RECORD CONTAINS Clause 


The RECORD CONTAINS clause, when specified without the "integer-1 TO" 
option, is for documentation purposes only. The compiler determines 
record size from tne data descriptions. When the "integer-i TO" 
option is specified, it forces the compiler to generate a variable 
length record file, even if the data descriptions describe fixed 
length records. 


Conversely, if the data descriptions for a sequential file describe 
variable-length records, the software sets up variable sized records 
automatically and ignores this clause. 


Even though the software ignores the values in the "integer-1 TO..." 
phrase, the clause may be used in any program to document record 
sizes. 


6.3.3 SAME RECORD AREA Clause 


The SAME RECORD AREA clause is identical for all file organizations. 
See Section: 6.1.3. 


6.3.4 RECORD BLOCKING 


The size of a file is expressed as an integral number of virtual 
blocks. Virtual blocks are physical storage structures. That is, 
each virtual block within a file is a unit of data whose size depends 
on the physical medium on which the file resides. 


Indexed files may reside only on disk. The size of virtual blocks 
within files on disk devices is always 512 bytes. 


Indexed files, like relative files, use a logical storage structure 
known as a logical block or bucket. A bucket consists of 1 to 32 
virtual blocks. The user may specify the number of virtual blocks 
contained within each bucket by using the BLOCK CONTAINS clause. This 
distinction should be made clear. A virtual block is a= physical 
entity which is fixed in size and cannot be changed by the user. A 
bucket is a logical entity and its size is directly under’ user 
control. Records may span virtual block boundaries. They may never 
Span bucket boundaries. 
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Increasing the bucket size increases the speed of processing of a file 
because fewer I/0 operations are needed to access the smaller number 
of buckets in the file. On the other hand, a larger bucket size means 
that more memory space is taken up by the I/O buffers. 


There are three ways that the bucket size may be specified by the user 
in a COBOL program: by default, by using the construct BLOCK CONTAINS 
integer RECORDS, or by using the construct BLOCK CONTAINS integer 
CHARACTERS. 


The default is to make the bucket size as small as possible to 
minimize the memory buffer space required. By uSing the BLOCK 
CONTAINS (integer RECORD or integer CHARACTERS) clause, you can 
increase the memory buffer space required. Increasing the buffer 
Space allows faster I/O by decreasing the number of operations to 
process a file. The following paragraphs further define the three 
blocking methods: 


Default 
The default philosophy is to make the bucket size as small as 
possible to minimize the memory buffer space required. The 
algorithms for calculating the bucket size follow: 
Bnum= ((22+Rlen)/512)+1 Fixed length record 


or 


Bnum= ((244+Rmax)/512)+1 Variable length record 


where: 
Bnum is the number of virtual blocks per. bucket. 
Rlen is the fixed record length (in bytes). 
Rmax is the maximum record length (in bytes) if the record 


length is variable. 


The number 22 comes from a bucket overhead of 15 bytes and a 
fixed length record header of 7 bytes; 24 comes from a bucket 
overhead of 15 bytes and a variable length record header of 9 
bytes. 


Table 6-6 gives the bucket size for record lengths. 


Table 6-6 
Bucket Size for Record Lengths 


Bnum Rlen Rmax 
1 1-499 | 1-488 | 
2 490-1082 489-1000 
| 3 1603-1514 | 1961-1512 
| 4 1515-2026 1513-2024 
5 2027-2538 | 2025-25 36 
6 2539-3058 2537-3048 
| 7 3051-3562 | 3049-3560 | 
| 8 3563-4974 3561-4972 
a 4875-4095 4973-4095 
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BLOCK CONTAINS Rnum RECORDS 
If the BLOCK CONTAINS num RECORDS clause is used, where num is an 
integer, then the following algorithms are used to calculate the 
bucket size. 
Bnum= ((15+(Rlen+7)*Rnum) /512)+1 Fixed length record 


or 


Bnum= ((15+(Rlen+9)*Rnum) /512)+1 Variable length record 


where: 
Bnum is the number of virtual blocks per bucket, ranging 
from: 1 to: 32. 
Rlen is the fixed record length (in bytes). 
Rmax is the maximum record length (in bytes) if the record 
length is variable. 
Rnum is the number of records per bucket as given in the 


BLOCK CONTAINS clause. 


The number 15 is bucket overhead, 7 is the fixed length record 
header and 9 is the variable length record header. 


BLOCK CONTAINS Cnum CHARACTERS 


If the BLOCK CONTAINS Cnum CHARACTERS clause is used, where Cnum 
is an integer, then Cnum is subject to the following constraints. 


(1) Cnum Rlen+1 for fixed length records 
or 
Cnum Rmax+3 for variable length records 
(2) Cnum mod 512=¢ 


Based on Cnum, the bucket size is calculated as follows: 


Bnum=Cnum/512 


where: 
Cnum is the number of characters per bucket as given in the 
BLOCK CONTAINS clause. 
Rlen is the fixed record length (in bytes). 
Rmax is the maximum record length (in bytes) if the record 
length is variable. 
Bnum is the number of virtual blocks per bucket, ranging 


from 1 to 32. 
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Violation of constraint (1) causes a fatal error and the default 
method is used to calculate the bucket size. Constraint (2) 
means that Cnum should be a multiple of 512. If not, a warning 
error is given and Cnum is increased to the next even multiple of 
512. 


The bucket size must be the same when the file is created and 
each time the file is accessed. Therefore, the BLOCK CONTAINS 
clause must never change for a particular file. 


Note: The previous discussion has used the following format: 


RECORDS 
BLOCK CONTAINS integer 


CHARACTERS 


If the following format is used: 


RECORDS 
BLOCK CONTAINS [integer-1 TO Jinteger-2 
ae CHARACTERS 


the compiler ignores integer-1, and integer-2 is used as the integer. 


L 
6.3.5 BUFFERING 


When the system performs a sequential or random input operation, one 
or more index buckets are read into the buffer area until the bucket 
containing the specified record is located. The bucket containing the 
record is then read into the buffer area. Any subsequent sequential 
read operations will use the current index buffer to locate and read 
subsequent records in the current or other record buckets. When it 
has exhausted the current index buffer (has read all the records 
identified in the bucket), the system reads the next index bucket into 
the buffer area. 


When performing a sequential or random output operation, the system 
moves a record from the files current record area into the files 
buffer. Each subsequent write operation moves ae record from the 
current record area into the buffer. The system writes the bucket to 
the medium wnen it has filled the buffer. Every cutput cperation also 
causes the appropriate index bucket to be read into the buffer area, 
the indexes for each of the keys to be added to the appropriate 


buckets, and the buckets to be rewritten to the storage medium. 


6.3.5.1 Buffer Size - Buffer size depends on the size of the largest 
record in the file and on the blocking factor. For indexed files, 
buffer size must be some multiple of 256 words (512 bytes). 


6.3.5.2 I/0 Buffer Areas - The RESERVE clause in the Environment 
Division specifies the number of I/O buffer areas to be allocated for 
each file. Each I/O area represents the space for one. bucket. A 
minimum of two is required for an Indexed file (this is the default). 
Three areas will increase the speed of random access. Four areas will 
increase the speed of random access if the file is being accessed on 
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two different keys. For each additional key, an additional area will 
increase the speed of access. Therefore, to speed up random access 
time, the optimum number of buffer areas is equal to the number of 
keys by which the file is being accessed plus two. Of course, each 
area means that more memory Space is being taken up. 


6.3.5.3 Buffer Space - To calculate the total amount of buffer space 
required for each Indexed file, the following algorithm may be used: 


Buffer Space = record size+((bucket size+2@)*no. of areas) 


+(48¥no. of keys in file)+((MAXKSIZ*24+MAXNKEY+3) /4 #4) 


+272 
where: 
MAXKSIZ is the maximum key size in the program. 
MAXNKEY is the maximum number of record keys for any file in 


the program. 


Note that in the division, the result is truncated to the next lowest 
integer. 


In addition to the above, there are 76 bytes of buffer space that are 
shared among all files and 44 times MAXNKEY bytes of buffer space that 
are shared among all indexed files. 


6.3.5.4 Sharing Buffer Space Among Files - The SAME AREA clause 
provides a simple method of sharing buffer space among several files. 


This clause is identical for all file organizations and is described 
in Section 6.1.6.4. 


6.3.6 INDEXED I/O STATEMENTS 


The COBOL I/O statements, CLOSE, DELETE, OPEN, READ, WRITE, REWRITE, 
and START can refer to indexed files. 


A COBOL program may open an indexed file in one of three modes, INPUT, 
OUTPUT, or I-0O, and access an open indexed file in one of three ways, 
sequentially, randomly, or dynamically. In INPUT mode, records may be 
read from the file; in OUTPUT mode, the file is created and records 
may be written to the file; in I-O mode, records may be read from the 
file, updated on the file, deleted from the file, or written to the 
file. The following table shows which statements and access methods 
apply to the three different OPEN modes of indexed files. 
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Table 6-7 
Indexed OPEN Modes 


1 


five Aseees 
Mode Statement Output T-0 


DELETE 

READ 
Sequential REWRITE 

START 


WRITE 


DELETE 
READ 
Random REWRITE 
START 
WRITE 


DELETE 
READ 

READ NEXT 
REWRITE 
START 
WRITE 








NOTE 


The term, current record pointer, used 
in the following sections, refers to a 
location in the operating system used to 
store the record number of available 
record ina file. 


6.3.6.1 Access Mode - The ACCESS MODE clause in the File-Control 
paragraph indicates which of the three access modes may be used on 
that file. When the ACCESS MODE clause specifies SEQUENTIAL, the I/0 
statements must refer to the records in the file sequentially, 


starting (after opening) with the first record and stepping through 
with each reference to the end of the file. 


When the ACCESS MODE clause specifies RANDOM, the I/O statements refer 
to the records in the file by the value of the key or keys. Usually 
the prime key is used unless a specific alternate key is designated. 
If an I/O statement refers to a record with a key, and that record 
does not exist, the INVALID KEY imparative statement may be executed 
depending on the particular I/0 statement used. (The INVALID KEY 
imperative statement is explained with each of the indexed I/0 
statements in this section.) 


When the ACCESS MODE clause specifies DYNAMIC, the I/O statements may 
refer to the records in the file either sequentially or randomly. The 
OTS determines which access method to use from the OPEN mode (INPUT, 
OUTPUT, or I-0) and the form of the I/O statement. For example, if 


the statement READ ...INVALID KEY is to aecess an open input file 
dynamically, the OTS uses the designated key for random access. If 
the statement READ NEXT ... is to access an open input file 


dynamically, the OTS sequentially accesses the next existing record. 
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The following sections (6.3.6.2 through 6.3.6.8) on using the I/0 
statements themselves contain additional information about access 
modes. 


6.3.6.2 Opening Indexed Files - The OPEN statement for an indexed 
file makes an INPUT, OUTPUT, or I-O mode file available so the COBOL 
program can access the records in the file sequentially, randomly, or 
dynamically. Consider the following example: 


Example 


The following sample OPEN statement opens the file named ARTICHOKE for 
input, and sets ARTICHOKE's current record pointer to the first record 
in the file. The program containing this statement could, after 
executing the statement, access ARTICHOKE with READ and START 
statements in the sequential access mode, READ statements in the 
random access mode, or READ, READ NEXT, and START statements in the 
dynamic access mode. 


+ 


we 


When the OTS 
Ss r 


executes an OPEN statement, it performs the following 
actions fo h 


e file named in the statement: 


e If the file is already open, the OTS generates an error 
message and performs the USE procedure section (if 
specified). (Section 6.8 discusses USE procedures and 
Section 12.3 discusses error messages.) 


e When opening an existing file, the attributes (i.e., record 
length, block size, ete.) of the file are used for accessing 
the file. Those specified in the program are ignored. Be 


sure that the. attributes specified in the COBOL program agree 
with the actual attributes of the file. 


® If a SAME AREA clause contains the name of the file and none 
of the other files named in the clause is open, the OTS 
allocates buffer space for the file. 


e When the file has passed all of the preceding checks and is 
ready for opening, the OTS instructs the Record Management 
Services to open the file. If the Record Management Services 
fails to open the file, the OTS reports an error condition 
and performs any applicable USE procedure (if present). 


e Finally, depending on which statements apply to the open 
mode, the OTS enables or disables all of the program's I/0 
Statements that refer to the file (see Table 6-7). For 
example, if the OPEN mode is INPUT, it enables all READ and 
START statements for that file and disables all REWRITE, 
DELETE and WRITE statements for that file. 


The OPEN statement sets the current record pointer for the file to the 
first existing record in the file as established by the prime record 
key. If the file is being accessed randomly or dynamically, the 
program should maintain correct values in the prime and aternate key 
fields. 
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6.3.6.3 Reading Indexed Files - When applied to a file being accessed 
sequentially, the READ statement makes the next logical record of an 
open file available to the program. The information made available is 
based on positioning by the OPEN, START, or last READ operation. 


When applied to a file being accessed randomly, the READ statement 
selects a specified record from an open file and makes it available to 
the program. The value of the specified key (prime key, if the no key 
is specified) identifies the record. 


When applied to a file being accessed dynamically, the READ statement 
has two formats so that it can either select the next logical record 
(sequentially) or select a specified record (randomly) and make it 
available to the program. The READ NEXT statement takes the number in 
the current pointer and finds the next present record. The following 
sample READ statement reads the file named ARTICHOKE sequentially and, 
when it exhausts the file, causes program control to transfer to the 
subroutine named FILEOUT: 


READ ARTICHOKE NEXT RECORD 
AT END GO TO FILEOUT. 


For more information concerning the mechanics of the READ NEXT 
statement see Section 6.3.6.6, Specifying the Next Record To Be Read. 


The READ with key takes the value in the specified key, moves it to 
the current record pointer, and reads the record being pointed to. 
The following READ (with key) statement reads the file named ARTICHOKE 
randomly, selecting records through the value in the file's primary 
key. If the designated key supplies a value that is not identified 
with a valid record, the statement causes program control to transfer 
to the subroutine named NO-REC. 


READ ARTICHOKE RECORD 
INVALID KEY GO TO NO-REC. 


Note: a random read repositions the current record pointer and thus 
effects further sequential reads. 


If the file has more than one record description, the records 
automatically share the same current record area. The OTS does not 
clear this area before it executes the READ statement (no blank 
filiing, ~ete.). Therefore, if the record read by the latest READ 
statement does not fill the entire current record area, the area not 
overlaid by the incoming record remains unchanged. For example, if 
the file's record area contains ten 3's, and a READ operation moves in 
a 6-character record containing all 1's, the current record area then 
contains six 1's followed by four 3's. Consider the following 
example: 


Current Record Area with all 3's 3333333333 
Next Record in the File 1111111 
Current Record Area after READ 1111113333 


6.3.6.4 Rewriting Records into. an Indexed File - The REWRITE 
Statement releases a logical record to an output or input-output file. 


In all of the access modes, the record is positioned based on the 
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prime key, any alternate keys are aiso processed properly, including 
duplicate keys. If more space is required for new record positions, 
the Record Management Services automatically extends the file size, 
regardless of the access mode being employed. 


If the file is open in sequential access mode and the records are not 
written in ascending order of the prime key values, an INVALID KEY 
condition exists. In any access mode an attempt to write an existing 
record having the same prime key value or an alternate key value where 
duplicates are not allowed, results in an INVALID KEY condition. 


The following sample WRITE statement releases the record BREAKERS to 
the indexed file. If the record already exists, program control 
transfers to WRITE-ERR. 


WRITE BREAKERS 
INVALID KEY GO TO WRITE-ERR. 


The indexed WRITE statement creates only storage files because 
pri fil 


AaAYna ganas iles. 


6.3.6.5 Deleting Records from an Indexed File - The DELETE statment 
logically removes an existing record from afile. After a DELETE 
Statement has successfully removed a record from a file, that record 
can no longer be accessed. 


If the file is open in the sequential access mode, the statement 
removes the record just successfully read. For example, the following 
sample statement removes the record just read from the file named 
ARTICHOKE: 


DELETE ARTICHOKE RECORD. 


If the file is open in either the random or dynamic access mode, the 
Statement removes the record from the record specified by the prime 
key. For example, the following sample statment deletes the record 
specified by the prime key from the file named ARTICHOKE. If the 
prime key supplies a value that does not contain a valid record, the 
statement transfers control to NO-REC. 


DELETE ARTICHOKE RECORD 
INVALID KEY GO TO NO-REC. 


6.3.6.6 Specifying the Next Record to be READ - The START statement 
Specifies which record will be the next record to be referenced 
sequentially in a file opened for INPUT or I-O processing. The START 
eae eae updates the current record pointer for future sequential 
READs. 


Suppose we have the following START statement: 

START FILE-A KEY IS EQUAL TO SUB-KEY-A. 
SUB-KEY-A must be alphanumeric. In addition, SUB-KEY-A must be a 
record key or alternate record key or subordinate to a record key or 
alternate record key whose leftmost character position corresponded to 


its own leftmost character position. For example, if the following 
fields were defined in the record: 
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@2 KEY-A. 
G3 SUB-KEY-A. 
@4 SUB-KEY-A1 PIC XXX. 
G4 SUB-KEY-A2 PIC Xx. 
@3 SUB-KEY-B PIC Xxx. 


and if KEY-A was a record key or alternate record key, then the 
following would be legal START statements: 


START FILE-A KEY IS EQUAL TO KEY-A. 
START FILE-A KEY IS EQUAL TO SUB-KEY-A. 
START FILE-A KEY IS EQUAL TO SUB-KEY-A1. 
The following START statements are illegal. 
START FILE-A KEY IS EQUAL TO SUB-KEY-A2. 
START FILE-A KEY IS EQUAL TO SUB-KEY-B. 


The leftmost character positions of SUB-KEY-A2 and SUB-KEY-B do not 
correspond to the leftmost character position of KEY-A. 


The relational operator IS EQUAL TO (or IS =) means that the current 
record pointer is set to point to the record associated with the first 
key equal to SUB-KEY-A. If SUB-KEY-A is shorter than the record key 
or alternate record key, then the record keys or alternate record keys 


in the file are truncated on the right to the same length as SUB-KEY-A 
for the purposes of the comparison. 
If the following START statement is used: 

START FILE-A KEY IS GREATER THAN SUB-KEY-A. 

or 

START FILE-A KEY IS > SUB-KEY-A. 
then the current record pointer is set to point to the record 
associated with the first key that is greater than SUB-KEY-A. Thus, 
if the file had records with the following keys: 


Record # 743 629 915 891 233 371 
KEY-A ABCDDZZX ABCDEABC ABCDEXYZ ABCDEZZZ ABCDGAAA ABCDGZZX 


and SUB-KEY-A contained ABCDE, then the current record pointer would 
be set to point to record number 233. 


If the following START statement is used: 
START FILE-A KEY IS NOT LESS THAN SUB-KEY-A. 
or 
START FILE-A KEY IS NOT < SUB-KEY-A. 
then the current record pointer is set to point to the record 


associated with the first key that is greater’ than or equal to 
SUB-~KEY-A. In the previous example that would be record number 629. 


cep) 
] 

Gd 
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If there is no record that satisfies the comparison, the invalid key 
exit is taken. In our example the following statement: 


START FILE-A KEY IS EQUAL TO SUB-KEY-A. 
would take the invalid key exit if SUB-KEY-A contained ABCDF. 


If the comparison is satisfied and the current record pointer is set, 
then subsequent READS would update the current record pointer using 
KEY-A as the key of reference. 


If the key phrase is not specified, then the default key is the prime 
record key and the default comparison is IS EQUAL TO. 


6.3.6.7 Closing Indexed Files - The CLOSE statement terminates 
processing on the file referred to in the statement. The following 
sample CLOSE statement terminates processing on the file named 
ARTICHOKE: 





CLOSE ARTICHOKE. 
whe ment closes a file, no otner I/0 operation can access 
tha file until another OPEN statement opens the file. If the 
statement specifies the LOCK option, the program cannot open the file 
again in that run. If a SAME AREA clause contains the name of the 
file just closed, the program may open one of the other files named in 
the clause. 


_ .. _ 
fi une 
1 


ct 
mt 


6.4 DEVICES 

The PDP-11 COBOL object time system supports any devices supported by 
the Record Management Services. Table 6-8 contains a partial list of 
these devices: 


Table 6-8 
Device Codes 


Device Device Code 


Card Reader 

Disk (RK@3/RK@5) 

Disk (RF11/RS11) 

Disk (RS@3/RSG4) 

Disk (RP11/RP@2/RP@3 ) 
Disk (RJP@4) 

Line Printer 


Magnetic Tape (TU1@8/TS@3) 


Magnetic Tape (TU16/TU45) 





*The DS device code does not apply to RSTS/E. 
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Some devices are better suited to certain uses than others. For 
example, since PDP-11 COBOL is a disk-oriented system, the disk 
provides COBOL files with the best performance and reliability. On 
the other hand, COBOL files on magnetic tape are limited to sequential 
organization. 


The following subsections discuss the devices that are available and 
how to use them to best advantage. 


6.4.1 DISK 


The primary means for storage and processing of PDP-11 COBOL files is 
a disk. Several disk units are supported, including RK@5, RF11, 
RP11/RP@3, RP@4Y and RS@4. Each device has its own file handling 
characteristics, and differs with respect to capacity, speed, and 
portability. The following table compares these characteristics. The 
values, low, mod (moderate), and high, describe the relative 
characteristics of the devices in the table. The efficiency 
characteristic commbines the values of capacity, speed, and 
portability for that unit into a single value. 


Table 6-9 
Comparison of PDP-11 Disk Devices 


Pe etl RF11 ee Ee el 













CAPACITY LOW/MOD LOW VERY HIGH | row 
(4800 (1924 at, | (82,000 (2948 
BLOCKS) | BLocKsS) | BLOCKS) BLOCKS) 
(RPG4 169,000 
BLOCKS) 












SPEED MOD HIGH HIGH 






PORTABILITY| HIGH (EASY) NONE HIGH (BULKY) NONE 








EFFICIENCY HIGH MOD HIGH 


nn 


*RSTS/E supports the RS@4 only as a swapping device. 
It cannot be used for user files. 


The characteristics of the devices in the table suggest suitable 
applications. Consider the following examples: 


@ The portable, moderate capacity RK#5 is ideal for storage of 
COBOL source and object files as well as small data files; 


e The fast, low capacity RF11 is ideai for scratch files requiring 
either random or sequential access; 


e The high-capacity RP11/RP@3/RP@4 is excellent for large files 
requiring high volume access in either the random or sequential 
modes. Further, its portability makes it ideal for master file 
storage on multiple systems. 


FILE HANDLING 


6.4.2 MAGNETIC TAPE 


All PDP-11 operating systems support magnetic tape files; all COBOL 
operations concerned with magnetic tape are fully supported by the 
compiler, including the MULTIPLE-FILE TAPE clause and the CLOSE REEL 
[WITH NO REWIND] clause. (RSTS/E does not support multi-reel files.) 


SS 


COBOL programs can use both the card reader and the line printer as 
I/O devices. 


If these devices have been assigned logical names in the Special-Names 
paragraph of the Environment Division, the ACCEPT and DISPLAY 
statements can access’ them. For example, consider the following 
coding: 


ENVIRONMENT DIVISION. 


| CARD-READER IS CARDS 
LINE-PRINTER IS LOG. 


SPECIAL-NAMES. | 
| 
PROCEDURE DIVISION. | 

| 


ACCEPT INREC FROM CARDS. 


DISPLAY PRINTREC UPON LOG. 





Figure 6-5 Assigning Logical Names to the 
Card Reader and Line Printer 


If filenames have been assigned to these devices in the SELECT clause 
of the File-Control paragraph, the READ and WRITE statements can 
access them for I/0 files. For example, consider the following 
coding: 
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FII® -CONTROL. 
| SELECT -INFILE ASSIGN TO "CR". 
SELECT OUTFILE ASSIGN TO: "LPs". 


FD OUTFILE 
DATA RECORD IS OUTREC. 







PROCEDURE DIVISION. 


READ INFILE. 







WRITE OUTREC. 






Figure 6-6 Assigning the Card Reader and 
Line Printer to Files 


6.5 FILES AND FILENAMES 


The OTS and the operating system use the device codes described in 
Section 6.4 to communicate with the devices. Further, the COBOL OTS 
uses the operating system's file specification and interfaces for all 
file manipulation with file storage devices (disk and magtape). The 
VALUE OF ID clause (discussed in the following subsection) in the FD 
entry describes the file specification to the OTS. The format for the 
full file specification follows: 


dev:[uic] filename.typ;version/switches 


where: 

dev: - device code 

[uic] - user's identification code or the code of the user 
for whom the file was created - the user directory 
ID. (The brackets [ ] are required.) 

filename - an alphanumeric field containing up to nine 
characters that identifies the file (RSTS/E allows a 
length of from one to six characters). 

typ - an alphanumeric field containing up to three 
characters that qualify the filename. 

version - a numeric field containing up to five octal digits 
that give the version number of the file. By 
specifying version numbers, the user can maintain 
several versions of the same file on a directory 
device. (Not available with RSTS/E.) 

switches - identifies certain actions for the operating system 


to perform for the file. (See Chapter 14, 
Optimization.) 
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These entries default as follows: 


dev: - the device code of the disk containing the operating 
system. 
[uic] - the user identification code of the user currently 


using the system. 
filename - null 
typ - null 


version - the version number defaults differently for IAS and 
RSX-11M input and output files. 


e input files - the highest numbered version of the 
file (thus selecting the latest version); 


@ output files - one greater than that of the 
highest numbered version of the file (thus 
creating the latest version). 


switches . - null 


For example, the following sample file specification causes the file 
system to process version 3 of a file on disk named ARIES. The user 
has an identification code of 149,222. 


DK: [148,222 JARIES; 3 


The following sample RSTS/E file specification causes the file system 
to process a file on disk named ARIES. The user has an identification 
code of 149,222. Note that RSTS/E does not support the version number 
feature. 


DK:[140,222]ARIES. 


6.5.1 USING EXPLICIT FILENAMES (VALUE OF ID CLAUSE) 
The VALUE OF ID clause, in the FD entry, describes the file 
specification to the COBOL OTS. The VALUE OF ID clause is optional; 
however, the system requires it whenever the program refers to an 
explicit file unless a sufficient file description is provided in the 
ASSIGN clause. The clause accepts either a literal entry or an 
identifier entry. Consider the following sample literal form of the 
clause: 


VALUE OF ID IS "DK:[14@,222]ARIES;3" 
Elements of the file specification appearing in the VALUE OF ID clause 
Supersede their counterparts specified in the ASSIGN clause for the 
file. (Subsection 6.5.2 discusses the ASSIGN clause.) 


When written in the literal form, the literal may be a complete file 
Specification or a part of a file specification. 


When written in the identifier form, the value of the identifier may 
be a complete or partial file specification. 


The identifier form of this clause is especially useful when different 
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runs of a program process different files. If a program muSt process 
different files in the same way on different runs, an ACCEPT statement 
in the Procedure Division can request a file specification from the 
user at the user's console or from a batch input stream. 


The following example illustrates how a COBOL program could request a 
file specification from an interactive terminal: 


DATA DIVISION. 


FD FILEIN 
VALUE OF ID IS INFILE. 


WORKING-STORAGE SECTION. 
77 INFILE PIC X(2@). 
PROCEDURE DIVISION. 


DISPLAY "TYPE IN INPUT FILE SPEC". 
ACCEPT INFILE. 


OPEN INPUT FILEIN. 


This sample coding causes the following interaction between the 
program and the user (the message printed by the program is 
underlined): 


TYPE IN INPUT FILE SPEC 
DK 1: THOREAU RET 


Following this interaction, the sample OPEN statement will open (for 


input) the file, THOREAU on DKi. 
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If the VALUE OF ID clause does not specify a complete file 
specification, the ASSIGN clause in the File-Control paragraph can 
assign a defalt to those components not specified. The ASSIGN clause 
must be written as part of the SELECT statement as shown below: 


SELECT THOREAU ASSIGN TO "DK1:" 
This example assigns a default device code "DK1:" for the location of 


the file THOREAU. Another device code specification in the VALUE OF 
ID clause could override it later in the source program. 


6.5.3 FILES D LOGICAL UNITS 





Each file in an executable task must have a unique Logical Unit Number 
(LUN) assigned to it. The COBOL compiler can only generate a relative 
LUN assignment for each file in a COBOL program, because there may be 
multiple COBOL programs in a task. (See Figure 2-18 which contains a 


A Faral TTIN mae tw ae 
sample file-to-relative-LUN assignment table.) Actual LUN assignments 


are “made by the COBOL Object Time System (OTS) at task execution time. 

The number of LUNs needed by a task is equal to 1+n, where n is the 
total number of individual files included in each program comprising 
the task. For example, if a task consists of three programs, each 
program requiring three files, then the number of LUNs required is 1@. 
(The first LUN is reserved for ACCEPT/DISPLAY and message 
processing.) If more than six LUNs are required for an executable 
task, the UNITS option must be specified at task~build time, because 
the Task Builder default is 6. 


Each LUN must have a physical device associated with it before the 
associated file can be opened. You can assign a physical device to 
the file by specifying the VALUE OF ID or ASSIGN clause in your COBOL 
program, or you can specify the ASG option at task-build time. 


NOTE 


The default LUN assignments generated by 
the Task Builder do not always equate to 
the system device. 


(Refer to the Task Builder Manual for your particular operating system 
for more information concerning task builder options.) 


As previously stated, each COBOL program receives relative LUN 
assignments for its files by the compiler. At task-execution time, 
the OTS converts these relative LUN assignments to actual assignments 
according to the following rules: 


1. If the task consists of only one COBOL program, the OTS adds 
1 to each of the relative LUN assignments yielding the actual 
assignments. Therefore, a ‘file receiving a relative LUN 
assignment of 2 by the compiler would receive an actual LUN 
assignment of 3 at execution time. 


2. If the task consists of more than one COBOL program having 


files assigned to it, simply adding 1 to the relative LUN 
assignments would obviously yield duplicate actual LUN 
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assignments. The OTS, in the case of multiple program tasks, 
utilizes the relative assignment +1 formula for the first 
program in the task. For each subsequent program, it takes 
the highest actual LUN assignment for the previous. program 
and adds 1 to it to arrive at the first LUN assignment. It 
then applies the +1 formula to this first LUN assignment to 
arrive at each subsequent assignment for the program. 
Consider the following example: 


Example 


A task consists of three programs (PROGA, PROGB, and PROGC). 
Each program has three files with relative LUN assignments of 
1, 2, and 3. At execution time, assuming that the programs 
were presented to the Task Builder or Merge Utility in the 
order PROGA, PROGB, and PROGC, the OTS would assign actual 
LUNs as follows: 


Program LUN assignment 


1 (reserved for ACCEPT/DISPLAY and message 
processing) 





PROGB 

Ist. File 
end. File 
3rd. File 


SNM 
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6.6 COMMUNICATING WITH THE PROGRAM 


The ACCEPT and DISPLAY statements allow low-volume, terminal-oriented 
interaction between a COBOL program and the user of the program. 


While these statements are primarily intended for use with keyboard 
devices, PDP-11 COBOL allows the ACCEPT statement to accept cards from 
a card reader, and the DISPLAY statement to display data on a line 
printer. The following two Sections (6.6.1 and 6.6.2) discuss these 
capabilities in greater detail. 


6.6.1 USING THE ACCEPT STATEMENT 


The ACCEPT statement makes small amounts of data available to the 
specified data item. 


Consider the following example; it causes data to be transferred from 
the device identified by the mnemonic-name, OPERATOR, to the area 
represented by the identifier, COMM-AREA. 


ACCEPT COMM-AREA FROM OPERATOR. 


OPERATOR must be a mnemonic-name specified for a device in the 
Special-Names paragraph (in this example, possibly the console). The 
area represented by the identifier COMM-AREA receives the data 
requested without any editing. 


The ACCEPT statement causes the transfer of a stream of bytes from the 


previous example). If the FROM phrase is not present, the data is 
transferred from the user's console. 


Enough bytes are transferred to fill the identifier's area. The size 
of COMM-AREA in this example dictates the number of bytes being 
transferred. 


If the device contains more data than there are bytes in COMM-AREA, 
the data is truncated. 


e If the length of the identifier exceeds 88 bytes, the OTS 
performs one or more additional transfers of data until it 
either fills the identifier or transfers less than 8@ bytes. 


e If the length of the identifier is less than or equal to 8@ 
bytes and the length of the data is less than the identifier 
on a teletype or cards, the OTS pads the identifier with 
blank characters. 


The ACCEPT statement has a second format that allows it to retrieve 
the current DAY, DATE, or TIME from the system, and store it in the 
specified identifier. (DAY, DATE, and TIME are reserved words that 
the user does not define. The user must define identifiers into which 
to accept the values of DAY, DATE, or TIME.) The following’ sample 
statements place the current date into the identifier, GREENWICH, and 
the day of the year into the identifier, DAY-OF-YEAR: 


ACCEPT GREENWICH FROM DATE. 
ACCEPT DAY-OF-YEAR FROM DAY. 
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If the date were February 3, 1979, GREENWICH would contain 790203 
(YYMMDD), and DAY-OF-YEAR would contain 79034 (YYDDD). 


The systems provide the time as follows (HH is the hour; MM is the 
minutes; SS is the seconds; CC is the hundredths of a second): 


TIME -- HHMMSSCC 
If the time were 28 seconds after 5:15 PM, the systems (which have a 
2 hour clock) would provide the numbers 17152000. (Since the PDP-11 
clock has no hundredths of a second capability, the systems place 
zeroes in the last two positions.) 


The identifier receives the data according to the rules for the MOVE 
statement. Chapters 3 and 4 discuss the MOVE statement as oo to 
non-numeric fields (Chapter 3) and numeric fields (Chapter 4). 


6.6.2 USING THE DISPLAY STATEMENT 


The DISPLAY statement transfers small amounts of data from he 
specified data item or literal to the specified device. 


Consider the following example; it causes the transfer of data from 
the area represented by the identifier, COMM-AREA, to the device with 
the mnemonic-name, OPERATOR: 


DISPLAY COMM-AREA UPON OPERATOR. 


OPERATOR must be a mnemonic-name specified for a device in the 
Special-Names paragraph (possibly the console in this example). The 
area represented by the identifier, COMM-AREA, contains the data being 
transferred. 


The DISPLAY statement causes the transfer of a stream of bytes to the 
device specified in the UPON phrase if it is present (OPERATOR in the 
preceding example). If the UPON phrase is not present, the OTS 
transfers the data to the user's console. 


All of the bytes in all of the identifiers or literals in the DISPLAY 
statement are transferred first. The size of COMM-AREA, in this 
example, dictates the number of bytes being transferred. 


The system does not convert COMP items from binary to ASCII; it 
Simply transfers them as they exist in storage. 


If a single DISPLAY statement must transfer large amounts of data, 
that data must contain appropriate vertical and horizontal form 


control characters. If the data being transferred does not contain 
form control characters and the length of the data stream exceeds the 
device's single line capacity, the excess characters will all print in 


the last position (overprinting each other). 


Table 6-10 contains several of the terminal form control characters: 
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Table 6-10 
Form Control Characters 


Control 
Character Function 


BEL (CTRL Bell ringer 


HT (CTRL Horizontal tab 
(CTRL Line feed or line space (new line) 
(CTRL Vertical tab 
(CTRL Form feed to head of form 
(CIRL Carriage return 





When it has transferred all of the data from all of the items listed 
in the statement, a carriage return and linefeed character are 
automatically appended onto the data. The WITH NO ADVANCING phrase 
Suppresses this appending operation. 


NOTE 


The WITH NO ADVANCING phrase is an 
extension to the ANS-74 standard. 


6.7 FILE COMPATIBILITY WITH OTHER PROGRAMMING LANGUAGES 
All files generated by other programming languages are compatible with 
COBOL provided that they were generated using Record Management 
Services. Files generated by other file systems must conform to 
Record Management Services formats. 


6.7.1 WRITING FILES FOR OTHER PROGRAMMING LANGUAGES 

PDP-11 COBOL writes files that can be read only by languages using the 
Record Management Services system interface for user program I/O. 
When creating a file that is to be read by a language, that does not 
use the Record Management Services interface (i.e., BASIC-PLUS), 
adhere to the following restrictions: 


e Ensure that the file has sequential file organization. 


e Ensure that the file is not a COBOL print-file (no LINAGE or 
APPLY PRINT-CONTROL clauses are applicable to the file). 
Printer control is handled differently by each PDP-11 
programming language. 


e Do not use the ADVANCING option in WRITE statements when 
creating the file. 


The file may contain fixed-length or variable-length records, and the 
records should only contain only printable ASCII character data. 
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6.7.2 READING FILES WRITTEN IN OTHER PROGRAMMING LANGUAGES 


PDP-11 COBOL reads files that were written only by languages using the 
Record Management Services system interface for user program I/O. 
Before reading a file that was written by another language that does 
not use the Record Management Services interface, be certain that the 
file meets the following restrictions: 


e Ensure that the file is an ASCII file. 


e Ensure that the file does not have a carriage control 
attribute (the FORTRAN carriage control file attribute must 
not be set). 


FORTRAN meets these restrictions when it writes ASCII (not binary) 
data with formatted WRITE statements. However, the user must disable 
the carriage control attributes in the OPEN statement for the file. 


CALL OPEN (UNIT=n, CARRIAGE CONTROL="NONE" 


WRITE (n,1@@) list 
FORMAT Cx: s.c0% ) 


BASIC+2 is capable of reading and writing all Record Management 
Services files. Therefore, files written by BASIC+2 programs are 
compatible with COBOL. 


BASIC-PLUS meets all of these restrictions when it writes a formatted 
ASCII (sometimes called sequential) file as described in the 
BASIC-PLUS Language Manual. PDP-11 COBOL cannot read BASIC-PLUS 
Virtual Array files. 


6.7.3 DATA FILE TRANSPORTABILITY 


The user who wishes to transport data files from one language 
processor to another or from one system to another (RSX-11M to RSTS/E 
or vice versa) should be careful to write such files using the Record 
Management Services. Record Management Services is the only file 


~ am ae 


Non-printable ASCII characters are subject to misinterpretation by the 
different language processors and operating system utilities. If, for 
example, COBOL were to write records which contained COMPUTATIONAL 
(binary) data items, the values these items could contain would be 
written in the file in the same binary format as represented in _ the 
computer. Such binary values may look like non-printable ASCII 
characters such as CR, LF, CTRL/Z, escape, which could cause system 
utilities to perform in an unpredictable manner while processing the 
records. 


Other ways that non-printable ASCII characters can get into a file 
are: 


1. having data definitions that contain the USAGE IS INDEX 
clause; 


2. moving HIGH-VALUES or LOW-VALUES; 
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3. moving any redefinition of a COMP or USAGE IS INDEX field; 


4. reading a data file that contains non-printable ASCII 
characters; 


5. having multiple record definitions of varying sizes. and 
filling a shorter record area then writing a longer one. 
(The excess characters, not filled, may be non-printing.) 
4 
This list is not complete. There are many other ways for non-printing 
ASCII characters to find their ways into printable ASCII files. 


6.8 PROCESSING I/O ERRORS - USE STATEMENT 

The USE statement provides COBOL programs with a way to process I/0 
errors. It allows the program to specify possible recovery steps 
following the I/O handling procedures performed by the software. 


When a COBOL program contains a USE procedure and an I/O error occurs, 
the OTS and Kecord Management Services execute their standard Ii/06 
error handling procedures and then transfer control to the procedure 
following the USE statement. (For further information concerning 
run-time I/O errors, see section 12.3.) 


Consider the following sample coding. When either THOREAU or 
ARTICHOKE causes an I/O error, the OTS executes its standard I/O error 
procedures and then transfers control to the paragraph (or paragraphs) 
that follow the USE statement. 


PROCEDURE DIVISION. 
DECLARATIVES. 
REPAIR SECTION. 
USE AFTER STANDARD ERROR PROCEDURE 
ON THOREAU ARTICHOKE. 
DISPLAY-ERROR. 
IF 


The paragraphs following the USE statement may contain any valid COBOL 
statement, except for the following: 


1. Those statements that refer to a procedure outside of the 
DECLARATIVES. (Any attempt to transfer control out of the 
DECLARATIVES causes the OTS to abort the program.) 


2. Those statements that would cause the USE procedure being 
executed to be invoked again. (Recursive USE procedures 
cause the OTS to abort the program.) 


USE procedures are executed in the same manner PERFORM ranges 
in Procedure Division coding. Therefore, paragraphs with the 
USE procedure section should follow all rules specified for 
paragraphs within PERFORM ranges. For further information on 
PERFORM ranges, see Use of the PERFORM Statement in Chapter 7 
of this guide.) 


If a status key is declared for the file in error, all status 
information is made available for processing in the USE 
procedure. 
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GOOD PROGRAMMING PRACTICES 


7.1 FORMATTING THE SOURCE PROGRAM 


Since most COBOL programs are usually long, the programmer needs 
techniques that will help him to simplify and improve the readability 
of his COBOL programs. The guidelines in this chapter, if followed, 
will help produce source programs that are easy to read and maintain. 


Before considering these guidelines, consider the reference formats 
that are available with PDP-11 COBOL: 


1. the Conventional (ANS) format, and 
2. the Terminal format. 


Although the Conventional format produces ANS compatible programs, it 
also produces source printouts that are somewhat more cluttered than 
those produced by the Terminal format. These guidelines, therefore, 
recommend the use of Terminal format and all of the following 
suggestions and examples assume the use of that format. Besides’ the 
obvious advantage of an uncluttered printout, the Terminal format has 
other programming advantages: 


1. it requires less storage area; 
2. it requires no line numbers; 
3. its statements may be aligned with tab characters. 


Further, whenever required, the REFORMAT utility program will convert 
Terminal format programs to the Conventional format. (The REFORMAT 
utility program is discussed in Chapter 11). 


The following suggestions should help to further simplify even the 
most complicated source programs. 


1. Begin division, section, and paragraph names in column 1. 
Although these names may start anywhere in Area A, aligning 
them in column 1 produces a much more readable listing. When 
required, place the * and - in column 1. (Column 1 then 
becomes column 0.) 


2. Insert a blank line, or one or more comment lines (describing 
the purpose of the file) before each SELECT statement in the 
FILE-CONTROL paragraph. Place the phrases of the SELECT 
statement on separate lines and begin each of them in column 
5 (use the tab character to skip over Area A). Consider the 
following illustration of a typical SELECT statement: 
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AREA A AREA B 


| De heh en at OR OUNE oe 
SELECT MASTER-FILE 
ASSIGN TO "DKi:" 
ORGANIZATION IS RELATIVE 
ACCESS IS SEQUENTIAL. 


Place the phrases of the file description statement on 
separate lines and begin each of them in column 5. (Use the 
tab to skip over Area A.) Consider the following illustration 
of a typical file description entry: 


AREA A AREA B 
de 230° 3x Sina Se Oe 
FD MASTER-FILE 


LABEL RECORDS ARE STANDARD 
VALUE OF ID IS MASTER~FILE-NAME 
DATA RECORD IS MASTER-RECORD. 


In both the File and Working-Storage sections, begin all Ol 
level items in column l. 


Indent, by four columns, all subordinate items with 
higher-valued level numbers. (For example, if the item that 
is subordinate to a 0l-level record description is 05, begin 
the record description level number in column 1 and the 05 
level number in column 5.) Use the tab character for the 
first indentation, a tab and four spaces for the second, two 
tabs for the third, etc. When indented in this manner, the 
listing will show, clearly and neatly, the hierarchical 
relationships of all of the data names in the program as well 
as their level number values. 


Increment level numbers by 5; then later, if it becomes 
necessary to insert additional group items, they may be 
inserted without having to change the level numbers of all 
items that are subordinate to that group. 


If desired, write the level numbers as single digits (such as 
1 instead of Ol). 


Use level number 01 instead of 77 in the Working-Storage 
Section. (77, aS a level number has the same meaning as Ol, 
and 77 may eventually be omitted from the COBOL standard.) 


Since all elementary items, except for index data items, 
require PICTURE clauses, these clauses fill a good part of 
the source program listing. However, the PICTURE clause 
itself may be simplified to enhance the listing's readability 
as follows: 


a. use PIC as an abbreviation for PICTURE, 
b. omit the noiseword IS, and 


c. align the PIC clauses on successive lines. (Use the tab 
character to align the clauses.) 


Put all paragraph name declarations in the Procedure Division 
on lines separate from the statements in the paragraph. This 
not only makes the program more readable, it also makes 
modification of the first statement in the paragraph easier. 
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Follow all imperative statements with a period, making them 
l-statement sentences. Place only one statement on a line. 
In addition to making the lines shorter and more _ readable, 
this will prove quite helpful when debugging the program. 
For example, if the program contains a coding error, it will 
be on one line and therefore easier to modify without 
affecting the other portions of the sentence; further, the 
diagnostic messages will refer to the correct line and their 
meanings will be clearer. 


Since left-aligned statements in any program enhance the 
readability of that program, develop the habit of starting 
all COBOL sentences in column 5. (Use the tab character to 
skip over Area A.) Some statements, however, should be 
further indented, as explained in the following paragraphs. 


If the true path of a conditional statement contains another 
conditional statement or more than one imperative statement, 
place all statements in the true path on lines immediately 
following the conditional statement and indent them to show 
their dependence upon that statement. Consider the following 
illustration of an IF statement and its true path: 

oe 


M 


TITOIN—-MAV YS MAYV—T TMT™M 
vi vy 2h FF LEAMA 


COMP aViids 

SUBTRACT TAX-LIMIT FROM COMPUTED-TAX GIVING EXCESS-TAX 
MOVE TAX-LIMIT TO COMPUTED-TAX 

ADD EXCESS-TAX TO TOTAL-EXCESS-TAX. 


If the statement has an ELSE (or false) path, align the word 
ELSE under the preceding IF and indent all statements that 
are dependent on the ELSE statement. Thus: 


IF condition 
true path statement 
true path statement 
ELSE 
false path statement 
false path statement. 


Be sure to place the period after the last statement only! 


Another good method for simplifying conditionals is to write 
only a single imperative statement in the true or false path. 
If the path requires more statements, place them in a 
separate paragraph and either PERFORM the paragraph from the 
path or GO to it. This technique avoids the possibility of 
inadvertently placing a period at the end of a statement 
within the path, thereby terminating it prematurely. 


When writing a GO TO ... DEPENDING statement, place each 
procedure name on a separate line and indent them all. 
Consider the readability of the following sample statement: 


GO TO P35 
P40 
P45 
P60 
P65 
DEPENDING ON P-SWITCH. 
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8. When grouping statements into paragraphs and sections, use 
the following organizational ideas: 


Group together logical units of processing into a_ section. 
Select a section name that reflects the type of processing 
being conducted within that section (such as TAX-COMPUTATION 
SECTION, PRINT-LINE-FORMATTER SECTION, etc.). Follow the 
section name with sufficient comment lines to explain the 
processing that is carried out by the statements within that 
section. 


Make paragraph names as short and simple as_ possible. A 
numbered abbreviation of the section name often suffices. 
Thus the paragraph names in the TAX-COMPUTATION section might 
be TC10, TC20, TC30, etc. Use paragraph names sparingly, 
placing them only where the true and false paths of 
conditional statements require branch points for GO TO 
statements. If the temptation arises to give a paragraph a 
longer name in an attempt to reflect the type of processing 
in that paragraph, use comment lines instead. (Comment lines 
usually convey more information, more clearly.) 


When using simple numbered paragraph names, assign increasing 
numeric characters to sequential paragraphs. If the numeric 
portion of the names increases by 5 or 10, new ones may be 
inserted later without disturbing the sequence of the names. 


Do not use the PERFORM verb in the form, PERFORM a THRU b. 
If the paragraphs a thru b must be performed, place them in a 
section by themselves and PERFORM the section, thus avoiding 
the use of the THRU option. 


Place single paragraphs that are to be performed into 
sections and use the section name as the object of PERFORM 
verbs. Then, if future design changes introduce complicated 
conditional logic into the paragraph, requiring additional 
paragraph names, the PERFORM statements need not be altered. 


The preceding guidelines divide the Procedure Division into 
modular blocks of coding. If these guidelines are used, the 
following additional techniques may be applied. 


a. Restrict entry to all sections through the first 
Statement of the section by use of a GO TO, a PERFORM, or 
a "fall through" from the preceding section; 


b. Ensure that all GO TO statements refer to only section 
names or paragraph names that are internal to the section 
containing the GO TO statement. 


7.2 USE OF PUNCTUATION 


Avoid using the COBOL punctuation characters, comma and semicolon. 
They lend little to the readability of programs that have their 
statements neatly aligned, as discussed earlier in this chapter. 
Further, it is quite easy to misuse these characters, which can cause 
serious errors for many compilers. (Other compilers either ignore 
incorrect punctuation characters or flag them with warning messages.) 
At best, even when used correctly and in the proper places, they have 


no effect on the meaning of the program. 
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7.3 USE OF THE ALTER STATEMENT 


Avoid using the ALTER statement to change the flow of control in a 
program. It is impossible to test the setting of an alterable GO 
statement except by executing it. Also, unless explicit comments 
accompany an alterable GO statement, it is difficult to tell whether 
or not it is referenced by ALTER statements or what the possible 
destinations might be. All of this makes debugging programs that 
contain these statements quite difficult. There are two other 
techniques that may be used in their place: 


1. If control branches one of two ways (i.e., a binary switch), 
write the switch as a conditional variable. Consider the 
following sample coding: 


01 P-SWITCH PIC S9 COMP VALUE 0. 
88 NO-PRINT VALUE 1. 


MOVE 1 TO P-SWITCH 


IF NO-PRINT GO TO P40. 


P40. 
MOVE 0 TO P-SWITCH. 


2. If control branches more than two ways, use MOVE statements 
to place integers into a data item, and a GO TO... 
DEPENDING ... statement to test the data item and branch 
accordingly. Consider the following sample coding: 


O01 P-SWITCH PIC S9999 COMP VALUE 0. 


MOVE 1 TO P-SWITCH 


MOVE 3 TO P-SWITCH. 


GO TO 
PART-TIME 
PIECE-WORK 
HOURLY 
SALARIED-WEEKLY 
SALARIED-OTHER 
DEPENDING ON P-SWITCH. 
> FALL THROUGH IS A BUG 
DISPLAY "?17". 
STOP RUN. 


7.4 USE OF THE PERFORM STATEMENT 


The general rules for the PERFORM statement are augmented with the 
following rules: 


GOOD PROGRAMMING PRACTICES 


1. The endpoint of a section and the endpoint of the last 
paragraph in the same section are two distinct points. This 
Means that it is possible to execute a PERFORM of the 
section, then while that PERFORM is still active, to execute 
a PERFORM of the last paragraph. 


2. On the start of a PERFORM, if the end point of the new 
PERFORM is the end point of an already active PERFORM, the 
OTS aborts the task and issues an error message. 

3. At the end of any procedure, a check is made to see if he 
procedure being ended is the end of the most recent PERFORM 
range. If so, the most recent PERFORM range is exited. If 
not, the end point of the most recent procedure is checked 
against the end point of all currently active PERFORMs. 
If the end point of the procedure is the end point of any 
currently active PERFORM range, the OTS issues an error 
message and aborts the task because the perform ranges are 
not being exited in the reverse of the order in which they 
were entered. 


NOTE 


The OTS error messages are discussed in 
Section 12.4, Run-time Error Messages. 


7.5 USE OF LEVEL 88 CONDITION-NAMES 


Condition-names provide a convenient method for testing a value or 
range of values in a field. The use of condition-names makes programs 
easier to maintain, because it ensures a uniform method of testing 
fields and helps to reduce recoding when the specifications of the 
program change. 


The following example illustrates the use of condition-names and shows 
the advantages inherent in their use. 


Suppose the records of a file each describe a student in an 
educational institution (or an employee in a corporation). Some of 
the records contain categories of information which are not present in 
other records. A “code" field, which contains a digit or letter, 
indicates the presence (or type) of some categories; while a_ special 
value in the information itself (such as a numeric value being zero, 
negative, or maximum) indicates the presence of other categories. The 
processing of such a record may vary considerably depending on these 
indicator fields. The fields may require interrogation at various 
points in the program, and the interrogation may require more than a 
Simple relation test. 


Consider a “code" fieid that holds one of seven values, coded as a 
mnemonic character. For example, S,1,2,3,4,G,P might be seven values 
that indicate student categories of Special, lst year, 2nd year, 3rd 
year, 4th year, Graduate, and Postgraduate. The field is described as 
follows: 


05 STUDENT-CATEGORY PIC X. 
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Program logic requires certain processing for enrolled undergraduates, 
different processing for special students, and still different 
processing for all students except enrolled undergraduates. Without 
the aid of condition-names, statements might be written as follows to 
resolve this problem: 


IF STUDENT-CATEGORY = "S" ... 


IF STUDENT-CATEGORY NOT LESS THAN "1" 
IF STUDENT-CATEGORY NOT GREATER THAN "4" 


IF STUDENT-CATEGORY EQUAL TO "G" NEXT SENTENCE 
ELSE IF STUDENT-CATEGORY EQUAL TO "P" 
NEXT SENTENCE ELSE GO TO ... 


However, if various level 88 entries follow the STUDENT-CATEGORY 
description, as shown below, condition-names can simplify this coding. 


05 STUDENT-CATEGORY PIC X. 
88 UNDERGRADUATE VALUE "1" THRU "4". 
88 SPECIAL-STUDENT VALUE "S". 
88 GRAD-STUDENT VALUE "G" "Pp". 
88 SENIOR VALUE "4". 


ts 


$8& NON-DEGREE-STUDENT VALUE 
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Now, the following procedural statements can solve the problem: 


IF SPECIAL-STUDENT ... 
IF UNDERGRADUATE ... 
IF GRAD-STUDENT ... 


Procedural statements with condition-names are much easier to read and 
debug than those containing the complete test. For example, the 
procedural statements, IF UNDERGRADUATE ..., and IF STUDENT-CATEGORY 
NOT LESS THAN "1" IF STUDENT-CATEGORY NOT GREATER THAN "4" both 
accomplish the same thing, but the first statement is simpler and less 
confusing. 


In addition, the statement, IF NOT UNDERGRADUATE ... can test the 
category of not being an undergraduate, which is equivalent to any one 
of the following statements: 


IF NOT (STUDENT-CATEGORY NOT < "1" AND 
STUDENT-CATEGORY NOT > "4") 


or 


IF STUDENT-CATEGORY < "1" OR 
STUDENT-CATEGORY > "4" ... 


or 


IF STUDENT-CATEGORY < "1" NEXT SENTENCE 
ELSE IF STUDENT-CATEGORY > "4" NEXT SENTENCE 
ELSE GO TO ... 


Statements such as these are tedious to write and a frequent source of 
coding errors. Further, if a change creates a new student category, 
the recoding takes more time and is even more error prone. A careful 
and controlled use of condition-names forces a higher degree of 
programming control and checkout. If the program logic does. require 
the modification of the STUDENT-CATEGORY field, it can even be named 
FILLER thus removing the opportunity to shortcut the use of 
condition-names. 
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To apply condition-names, follow the description of the item to be 
tested with a level 88 entry. The item being tested, known as the 
conditional variable (STUDENT-CATEGORY in the preceding 
illustrations), may be either DISPLAY or COMPUTATIONAL usage, but not 
INDEX usage; it may also be a group item. 


The compiler stores all of the values supplied by the level 88 entries 
in the object program exactly as written. (They are pooled with all 
of the literals from the Procedure Division.) A value supplied by a 
level 88 entry for a conditional variable of COMPUTATIONAL usage is 
stored in binary format to save conversion at object time. The 
compiler stores all other values as byte strings with the proper 
attributes. It does not make the level 88 entries equal to their 
conditional-variables in size. This means that it neither truncates 
nor pads (with spaces) non-numeric literals. Further, it neither 
truncates nor pads (with zeros) numeric literals, but stores them as 
written or, if converted to binary, in the minimum size COMP item that 
will hold the converted value. It stores signs as_ trailing 
overpunches on numeric DISPLAY literals, and removes and remembers 
decimal points. 


Do not enter level 88 items under group items that have subordinate 
entries containing any of the following clauses: SYNCHRONIZED, 
JUSTIFIED, COMPUTATIONAL, INDEX. 


7.6 USE OF QUALIFIED REFERENCES 


7.6.1 Qualified Data References 


The COBOL language provides facilities to define and reference 
user-defined data items. Data items are programmer-defined variables 
declared in the Data Division of a COBOL program. Such variables 
include, among others, file record descriptions and internal working 
areas. These data items are processed by procedural statements such 
as the WRITE, MOVE, and ADD statements. Procedural operations on 
these data are facilitated through references to the data items by 
name. For example, to update a variable, YTD-GROSS-PAY, by a weekly 
gross pay amount WEEKLY-GROSS, write the program fragment shown in 
Figure 7-1. 


Fence eg Se ee ee es ee ee eg tf 


O01 YTD-GROSS-PAY PIC 9(5)V99. 
O01 WEEKLY-GROSS PIC 999V99. 


WORKING-STORAGE SECTION. 
| 


ne eevee ear 


ADD WEEKLY-GROSS TO YTD-GROSS-PAY. 


a a ee 


Figure 7-1 
Unqualified Data Item Reference 


In this example, YTD-GROSS-PAY and WEEKLY-GROSS are defined in the 
Working Storage Section of the Data Division as COBOL variables with a 
level number of 01. The variable representing the “year-to-date gross 
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pay (YTD-GROSS-PAY)" is computed by incrementing its present value by 
the "weekly gross pay (WEEKLY-GROSS)" amount through reference to’. the 
appropriate data items in the ADD statement. References are made to 
the data items by the singular, unqualified names of YTD-GROSS-PAY and 
WEEKLY-GROSS. Since YTD-GROSS-PAY and WEEKLY-GROSS are defined with 
level numbers of 01 in the Working Storage Section, these variables 
must be unique in their spelling and, hence, can only be referenced by 
the spelling of each data item's name without any COBOL qualification. 


The example in Figure 7-1 is artificial because the data item 
representing the "year-to-date gross pay" is defined as a level l 
variable in the Working Storage Section. More realistically, 
YTD-GROSS-PAY is defined as a field within an employee payroll record 
residing on an external master payroll file. The process of updating 
the "year-to-date gross pay" by a "weekly gross pay" amount is shown 
more appropriately in Figure 7-2. 


FILE SECTION. 
FD MASTER-IN 


LABEL RECORD IS STANDARD 

VALUE OF ID IS "MASTER.PAY". 
O01 PAY-RECORD. 

03 NAME PIC X(30). 

03 EMPLOYEE-NO PIC 9(9). 


03 YTD-GROSS-PAY PIC 9(5)V99. 


FD MASTER-OUT 
LABEL RECORD IS STANDARD | 
VALUE OF ID IS "MASTER.PAY". 

01 PAY-RECORD. | 
03 NAME PIC X(30). 

03 EMPLOYEE-NO PIC 99). 
03 YTD-GROSS-PAY PIC 9(5)V99. 


WORKING-STORAGE SECTION. 
01 WEEKLY-GROSS PIC 999V99. 


PROCEDURE DIVISION. 

INIT. 
OPEN INPUT MASTER-IN. 
OPEN OUTPUT MASTER-OUT. 


ADD WEEKLY-GROSS, YTD-GROSS-PAY OF MASTER-IN 
GIVING YTD-GROSS-PAY OF MASTER-OUT. 





Figure 7-2 
Qualified Data Item Reference 
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In this example, YTD-GROSS-PAY is defined as a field in both the input 
and output record descriptions. There are two separate data items 
whose spellings are identical. 


To reference each data item, it is necessary to qualify the name of 
each data item with sufficient information to constitute a unique 
reference. Thus, to reference the "year-to-date gross pay" amount in 
the output record, we write "YTD-GROSS-PAY OF MASTER-OUT" where such a 
reference is called a qualified reference. The filename MASTER-OUT is 
functioning as a qualifier in the reference. The reserved word "OF" 
is the qualification connector and may be used interchangeabely with 
the reserved word "IN" in this context. Another way of referencing 
the same data item is to write "YTD-GROSS-PAY OF PAY-RECORD IN 
MASTER-OUT". This reference is called a completely qualified 
reference because all possible qualifiers are specified in the 
reference. A reference of the form "YTD-GROSS-PAY" or "YTD-GROSS-PAY 
OF PAY-RECORD" is illegal since it does not uniquely identify which of 
the two data items is desired. Such a reference is termed an 
ambiguous reference, 


In the area of data item definition and referencing, COBOL is unlike 
other languages such as FORTRAN and ALGOL 60. While FORTRAN requires 
each data item to have a unique name (i.e., no two data items may have 
a name of identical spelling), COBOL relaxes this requirement to the 
extent that each data item must be uniquely referable. That is, two 
Or more data items may have their names spelled identically, but there 
must exist a way to reference each distinct data item. Thus, there is 
a distinction between a data item and its name. Central to 
understanding this distinction is understanding the concept of unique 
referability. 


The functionalities of data item definition and referencing may be 
understood by stating three guidelines which relate the concepts of 
data item definition, reference format, and unique referability. 


7.6.2 Guideline 1 (Data Item Definition) 


Each data item has a name. Each name is immediately preceded by an 
associated positive integer called its level number. A name either 
refers to an elementary item or else it is the name of a group of one 
or more items whose names follow. In the latter case, each item in 
the group must have the same level number, which must be greater’ than 
the level number of the group item. 


7.6.3 Guideline 2 (Reference Format) 


Data-name qualification is performed by following a data-name or 
condition-name by one or more phrases of a qualifier preceded by IN or 
OF. IN and OF are logically equivalent. The general format of a 
qualified reference to an elementary item or group of items named 
"name-O" is given in Figure 7-3. 


name-0 OF name-1l...OF name-m 
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where m >= 0 and where, for 0 <= j < m, name-j is the name of some 
item contained directly or indirectly within a group item named 
"name-jt+l". A reference of the form given in Figure 7-3 is called a 
(partially) qualified reference with name-1l,name-2,...,name-m being 
called qualifiers. Such a reference is termed a completely qualified 
reference if "name-j+l" is the father of name-j for 0 <= j <= m-l. 


In the hierarchy of qualification, names associated with an FD 
indicator are the most significant, then the names associated with 
level-number 01, then names associated with level-number 02,...,49. 
The most significant name in the hierarchy must be unique and cannot 
be qualified. Subscripted or indexed data-names, unsubscripted 
data-names, and condition variables may be made unique by 
qualification. The name of a condition variable can be used as a 
qualifier for any of its condition-names. Enough qualification must 
be mentioned to make the reference unique; however, it may not be 
necessary to mention all levels of the hierarchy as the example in 
Figure 7-2 demonstrates. 


7.6.4 Guideline 3 (Unique Referability) 


If more than one data item is defined with the same name "name-0", 
there must be a way to refer to each use of the name by using 
qualification. That is, each definition of "name-0O" must be uniquely 
referable. A data item is uniquely referable if the complete set of 
qualifiers for the data item are not identical to any partial 
(including complete) set of qualifiers for another data item. 


= 


7.6.5 Qualified Procedure References 


The facility of qualification may be applied to procedure references. 
A procedure name is either a paragraph or section name. By 
definition, a paragraph name iS wunigue only within a section 
containing the paragraph while, on the other hand, section names must 
be unique within a COBOL program. The general format of a qualified 
procedure reference is shown in Figure 7-4, 


paragraph-name OF section-name 


Figure 7-4 
General Format of a Qualified Procedure Reference 





A paragraph name may be qualified by its containing section name; a 
section name may never be qualified in a procedure reference. When a 
paragraph name is referenced without an explicit section name 
qualifier, the paragraph name is implicitly qualified by the 
appropriate section name. 


If a paragraph name is unique within a COBOL program it is not 
necessary to qualify the paragraph name in the procedure reference. 
Finally, if a paragraph name is not unique within a COBOL program, the 
paragraph name must be qualified in a procedure reference when the 
reference is made outside of the section which contains the paragraph. 
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7.6.6 Qualification and Compiler Performance 


Qualification is a powerful language facility for the development of 
COBOL programs. Used wisely, it increases the readability of COBOL 
programs. However, the user pays a price for utilization of this 
facility in terms of a slower compilation rate (i.e., COBOL source 
lines per unit of time). 


Qualification requires a tree-structured symbol table at compile-time. 
The time -required for building and looking up on a tree-structured 
symbol table is considerably longer than for a non-tree-structured 
symbol table. This translates into a general degradation of compiler 
performance. If qualification is not employed in a program compiled 
by the PDP-1l1 COBOL compiler, compilation speed is not affected. 
However, when qualification is used, the compilation rate slows down 
due to the additional system overhead. 


In general, if there are deeper levels of qualification, there will be 
a slower compilation. This is especially so at the end of the Data 
Division text where duplicate data-name declarations are detected by 
the compiler. Object-time performance is not affected by usage of the 
qualification facility. 


CHAPTER 8 


REFORMAT UTILITY PROGRAM 


PDP-11 COBOL accepts source programs that were coded uSing either’ the 
conventional 8f-column card reference format or the shorter, 
terminal-oriented PDP-ll terminal format. The REFORMAT utility 
program reads source programs that were coded in the terminal format 
and converts them to 8%-column conventional format source programs. 
The PDP-11 COBOL Language Reference Manual discusses both formats in 
detail. 


Consider the two formats: 


@ The terminal format is designed for ease of use with text 
editors controlled from an on-line console keyboard and is 
compatible for use with the PDP-1ll system. It eliminates the 
line-number and identification fields and allows horizontal 
tab characters and short lines. 


e The conventional format produces source programs that are 
compatible with the reference format of other COBOL compilers 
throughout the industry. 


REFORMAT lets you write source programs in the terminal format; then, 
if compatibility is ever required for any of those programs, it 
provides a simple method for conversion to the conventional format. 


REFORMAT follows the following steps to expand each line of terminal 
format coding to the conventional format: 


e It generates a 6-character line number of SPPF1B, places that 
number in the first six character positions of the line, and 
increases it by @PGPG1H for each subsequent line. 


@e It places any continuation or comment symbols (-,*, or /) into 
character position 7. 


@e It places the coding from the terminal format line into 
character positions 8-72, thereby creating a line of 
conventional format coding. 


e It replaces any horizontal tabs with the appropriate number of 
Space characters to simulate tab stops at character positions 
5,13,21,29,37,45,53,61, and 66 of the terminal format line. 


@e It moves spaces into any character positions left between the 
last character of coding and character position 73; 
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e It places either identification characters (if they were 
supplied at program initialization) or spaces into character 
positions 73-89; 


e It right justifies (at position 72) the first line of a 
continued non-numeric literal, thus guaranteeing that the 
literal will remain the same length as it was in the default 
format; 
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e It creates a line containing a slash (/) in position 7 and 
Space characters in positions 8 through 72 for every form-feed 
character that it encounters. 


REFORMAT Command String 


Since REFORMAT is written in COBOL, it runs as a COBOL object program. 
It has no logical switches. To run it, enter the following command: 


RFM RET 


This causes REFORMAT to begin execution. REFORMAT immediately 
requests the file specifications for the two files (input and output) 
to be processed. In response to its prompting messages, type in the 
file specifications for your two files. 


RFM-INPUT FILE SPEC: 
RFM-OUTPUT FILE SPEC: 


When the system has successfully opened both files, REFORMAT types the 
following request for an identification entry in columns 73 through 
88. If you desire an identification entry, type in from one to eight 
characters. REFORMAT places these characters, left justified, in 
columns 73 through 8@ of each output line. If no entry is required, 
type a carriage return. 


RFM-COLS 73 TO 8: 


OF 


writes it 
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as 8f-character 
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When it has processed the last record in the file, REFORMAT displays 
the following messages; the first indicating the number (nnnnn) of 
output records produced and the second requesting another input file. 


RFM-nnnnn LINES PROCESSED. 
RFM-INPUT FILE SPEC: 


If there is another file to be reformatted, follow the same sequence 
with the specifications for the next file. If not, type CTRL-Z to 
terminate execution. 
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REFORMAT Error Messages 


If any of the responses to the prompting messages contain detectable 
errors, REFORMAT displays the following messages indicating the 
problem. 


RFM-ERROR IN OPENING INPUT FILE 
RFM-TRY AGAIN 
RFM-INPUT FILE SPEC: 


The system could not open the input file. Either the file is not 
present on the device specified (the default device is SY:) or the 
file name is typed incorrectly. The usual I/O error messages precede 
this message. 


To continue processing that file, examine the input file spec and type 
in a corrected version. To process another file, type in a new input 
file specification. To terminate execution, type CTRL-Z. 


RFM-ERROR IN OPENING OUTPUT FILE 
RFM-TRY AGAIN 
RFM-OUTPUT FILE SPEC: 


The system could not open the output file. An incorrectly typed file 
specification usually causes this error. (The default device is SY:.) 
The usual I/O error messages precede thiS message. To continue, 
examine the output file specification and type in a corrected version. 
To terminate execution, type CTRL-Z. 


RFM-INPUT FILE IS EMPTY 
RFM-INPUT FILE SPEC: 


The system successfully opened the input file, but the first READ 
Statement encountered the AT END condition. 


To continue, type in a new input file specification for another file. 
To terminate execution, type CTRL-Z. 


RFM-ERROR IN READING INPUT FILE 
RFM-INPUT FILE SPEC: 


The first attempt to read the input file was unsuccessful. This error 
is usually caused by an input record length exceeding 86 characters. 
(Although terminal format records should not exceed 66 characters in 
length, REFORMAT provides a record area of 86 characters and ignores 
the right-most 29 characters.) 


To continue, type in a new input file specification for another file. 
To terminate execution, type CTRL-Z. 


RFM-ERROR IN READING INPUT FILE 
RFM-REFORMATTING ABORTED 
RFM-nnnnn LINES PROCESSED 
RFM-INPUT FILE SPEC: 
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While reading input records (other than the first record), REFORMAT 
was unsuccessful in an attempt to read a record. It terminates 
execution and closes both files. 


To process another file, type in a new input file specification and 
continue with the prompting message seguence. To terminate execution, 
type CTRL-Z. 


RFM-ERROR IN WRITING OUTPUT FILE 
RFM-REFORMATTING ABORTED 
RFM-nnnnn LINES PROCESSED 
RFM-INPUT FILE SPEC: 


REFORMAT was unsuccessful in an attempt to write an output record. It 
terminates execution and closes both files. 


To process another file, type in a new input file specification and 
continue with the prompting message sequence. To terminate execution, 
type CTRL-Z. 


CHAPTER 9 


SEGMENTATION 


PDP-11 COBOL allows you to break the Procedure Division up into 
overlayable and non-overlayable program segments to optimize memory 
utilization. An overlayable program segment can be overlayed by any 
other overlayable segment. A non-overlayable program segment, 
however, can never be overlayed. 


NOTE 


The object code generated for the 
Identification Division through the Data 
Division is non-overlayable. 


9.1 USING THE PDP-11 COBOL SEGMENTATION FACILITY 


The PDP-i1l COBOL Segmentation Facility allows you to specify your own 
segmentation requirements. To effect segmentation, you must define a 
segment limit by specifying the SEGMENT-LIMIT IS clause in the 
Environment Division of your source program. The value you specify in 
this clause is used by the compiler as a basis for determining whether 
a program segment is overlayable or non-overlayable. A segment 
consists of one or more COBOL sections. Each COBOL section should be 
composed of a series of closely related operations designed to 
collectively perform a particular function. To designate a section as 
belonging to an overlayable or non-overlayable segment, assign a 
segment number to it using the following format: 


Section-name SECTION segment-number. 
Where: 


Section-name Is a user-defined COBOL word that names’ the 
section 


Segment-number Is an integer ranging from 0 to 49. 


If you specify a segment-number whose value is less than the value 
specified in the SEGMENT-LIMIT IS clause, you have defined the section 
as being non-overlayable. A segment-number whose value is greater 
than or equal to the value specified in the SEGMENT-LIMIT IS clause 
defines the segment as being overlayable. 
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9.1.1 Programming Considerations 


The most frequently used sections of your program should be made 


non-overlayable. Assign segment-numbers that are less than the value 
specified in the SEGMENT-LIMIT IS clause to these sections. 
Infrequently used sections should be made overlayable. Assign 


segment-numbers that are greater than or equal to the value specified 
in the SEGMENT-LIMIT IS clause to these sections. Sections that 
communicate with each other should be assigned to the same segment. 
Assign the same segment-number to these sections. Sections having 
identical segment-numbers are assigned to the same segment. 


9.2 SEGMENTATION AND THE PDP-11 COBOL COMPILER 


The previous sections told you how to effect segmentation. This 
section tells you what segmentation means in terms of code generation. 
The PDP-11 COBOL compiler breaks up the object code it generates into 
program sections called PSECTs. One or more PSECTs are generated for 
each program SECTION. The maximum size PSECT generated is 2000 
decimal words. However, this maximum size can be altered by 
specifying the /CSEG:nnnn switch in the compiler command line. 
(PSECTS are described in Appendix D: The /CSEG:nnnn Switch is 
described in Section 9.4, and Section 2.5.3). 


Also generated, are Overlay Description Language (ODL) directives that 
group together all PSECTs that belong in the same overlay. These ODL 
directives are placed in an ODL file to be used as input to the Task 
Builder. The Task Builder uses the ODL file to generate a task image 
containing the correct combination of overlayable/non-overlayable 
PSECTs. 


If the source program is written without explicit segmentation, all of 
the generated PSECTS are concatenated into one non-overlayable 
program. If the source program does contain explicit segmentation, 
ODL directives are created to group PSECTs together into the correct 
combination of overlayable and non-overlayable program segments. 


9.3 SEGMENTATION USING THE /OV SWITCH 


The /OV switch, when appended to the compiler command line, directs 
the compiler to produce ODL directives that make all of the procedural 
PSECTS overlayable. Therefore, the amount of memory required to store 
the program is equal to that required to contain the root 
(non-overlayable portion) and the largest PSECT. (See Figure 9-l, 
Segmentation Using The /OV Switch; and Section 2.5.3, Compiler 
Switches). 


The /OV switch is particularly useful for quickly segmenting programs 
that were written without explicit segmentation or for overriding 
explicit segmentation. 
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Figure 9-1 Segmentation Using the /OV Switch 


9.4 USING THE /CSEG:nnnn SWITCH 


The PDP-1l1 COBOL compiler generates a PSECT for each COBOL section. 
If the code generated for a particular section exceeds the default 
maximum size for a PSECT (4000 decimal bytes), more than one PSECT is 
generated. PDP-11l COBOL provides a switch (/CSEG:nnn) that allows you 
to control the size of PSECTs generated by the compiler. (See Section 
5.2.3 Compiler Switches). 


If, for example, you compile a program that produces a PSECT that is 
too large to be task built, you can recompile the program using the 
/CSEG:nnn switch to reduce the size of the PSECTsS generated. See 
Figure 9-2 for an example of using the /CSEG:nnnn switch. 
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Command Line (Without /CSEG:nnnn switch specified) 


CBL> CBLMRG,CBLMRG/MAP=CBLMRGC er) 


SEGMENTATION MAP 

SECTION NAME SEGMENT NO. NAME 
OUTPUT-ODL-USE 00 $cso0ol 000172 00061 
INPUT-ODL-USE 00 $c$002 000172 00061 
MAIN-CONTROL 00 $c$003 003336 00879 


PROCESS-INPUT-ODL 00 $cs004 001130 00300 
HDR-CHECK 00 $C$005 000322 00105 


* One large PSECT is generated 


Command Line (With the /CSEG:nnnn switch specified) 


CBL> CBLMRG,CBLMRG/MAP/CSEG:1000=CBLMRGC&) 


SEGMENTATION MAP 


SECTION NAME SEGMENT NO. NAME 


OUTPUT-ODL-USE 00 $csool 000172 
INPUT-ODL-USE 00 $cs$002 000172 
MAIN-CONTROL 00 $c$003 001744 

00 $c$004 001426 
PROCESS-INPUT-ODL 00 $cs005s 001130 
HDR-CHECK 00 $cs006 000322 


* Two PSECTs are generated 





Figure 9-2 Using the /CSEG:nnnn Switch 
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CHAPTER 10 


INTER-PROGRAM COMMUNICATIONS 


Inter-program communications is the passing of control and optional 
data from one program within a task to another. PDP-1l COBOL provides 
you with the ability to Task-build separately compiled COBOL programs 
into a single task image. During task execution, these separately 
compiled programs can communicate with each other via the COBOL CALL 
statement. 


A task can consist of a stand-alone program or a main program and one 
or more subprograms. A stand-alone program is one that does not caii 
subprograms and cannot itself be called. A COBOL main program is one 
that calls subprograms but can never be called in return. A COBOL 
subprogram, however, is always called by another program, either the 
main program or a subprogram. Inter-program communications deals only 


with main programs and subprograms. 


Developing a program aS a main program and a set of subprograms offers 
a number of advantages: 


1. Large monolithic programs are no longer’ required. These 
large programs can be replaced by a controlling main program 
and a set of subprograms, where each subprogram is designed 
to perform a well-defined function. 


2. Small subprograms can be developed independently by several 
members of a programming staff. 


3. Small subprograms can be tested more easily than large 
programs. 


4, Small subprograms can be modified and recompiled faster than 
large programs. 


5. General purpose subprograms can be developed and used in more 
than one programming application. 


10.1 COBOL MAIN PROGRAMS VS SUBPROGRAMS 


A COBOL main program is one that calls other programs (subprograms) 
but cannot be called in return. A COBOL main program contains at 
least one CALL statement. A COBOL subprogram is one that is called by 
another program, either the main program or another subprogram. The 
main program is automatically activated at task execution time. A 
subprogram, however, is activated only when called by another program. 


The COBOL compiler differentiates between a main program and a 


Subprogram by the presence or absence of a USING phrase in the 
Procedure Division header of the program being compiled. The USING 
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phrase is used only in COBOL subprograms. It defines the program as 
being a subprogram and optionally identifies the data expected from 
the calling program. The Procedure Division header has the following 
format: 


PROCEDURE DIVISION [USING [data-name-l , data-name-2]...]. 
A subprogram, that does not process data (arguments) passed to it by a 
calling program, has only the word USING appended to the Procedure 


Division header. For example: 


PROCEDURE DIVISION USING. 


A subprogram that processes passed data, has a USING phrase with one 
or more data-names specified. If a data-name(s) is specified, the 
program must also contain a Linkage Section in the Data Division. The 
Linkage Section describes the size and type of data being passed. 
(See Figure 10-1, Sample LINKAGE SECTION and USING phrase). 








LINKAGE SECTION. 






* SUBPROGRAM-DATA. 








01 1ST-PARAMETER PIC X(5). 
OF 2ND-PARAMETER PIC X(5). 


01 3RD-PARAMETER PIC X(5). 












PROCEDURE DIVISION USING 2ND-PARAMETER, 3RD-PARAMETER. 


NOTES 


1. All of the data-names appearing in the using phrase must also 
appear in the LINKAGE SECTION. 


2. Not all of the data~names in the LINKAGE SECTION need appear 
in the USING phrase. 


3. A LINKAGE SECTION can appear in a subprogram even if the 
USING phrase does not contain a data-name. However, if any 
of the data-items contained in the LINKAGE SECTION are 
referenced in procedures, the compiler will issue a fatal 


as ARoekin 
| qgiagnoscic. | 


Figure 10-1 Sample LINKAGE SECTION and USING Phrase 


10.1.1 Calling a COBOL Subprogram from a COBOL Program 
To call a subprogram from a COBOL program, a CALL statement having the 


r nm 
following format must be used: 


CALL literal [USING data-name-1 [, data-name-2]...]. 
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Where: 
literal is the name that appears in the PROGRAM-ID entry 
of the called program. 
data-name-1 identify those data-items in the calling program 
through that can be referred to by the called program. 


data-name-n 


10.1.2 Returning from a COBOL Subprogram 


In addition to the required USING phrase and optional LINKAGE SECTION, 
a subprogram should contain at least one EXIT PROGRAM statement. The 
EXIT PROGRAM statement identifies the subprogram return point. That 
is, the point in the subprogram at which control is returned to the 
calling program. If the EXIT PROGRAM statement is missing, the COBOL 
compiler will generate one after the last statement in the program. 


NOTE 
More than one EXIT PROGRAM statement is 
allowed in a subprogram. 


10.2 UNIQUENESS OF PSECT NAMES 


The names of all PSECTs within a task must be unique. When atask is 
composed of more than one COBOL program, you must insure that the 
PSECTsS generated by the COBOL compiler for each program are unique. 
(See Section D.1, PSECT Naming Conventions). 


10.3 COBOL OTS - ERROR CHECKING 


At task execution, the COBOL OTS performs a check to insure that the 
number of arguments passed to a called COBOL subprogram is the same as 
the number expected. That is, the subprogram Procedure Division USING 
phrase must contain the same number of data-names as the USING phrase 
in the calling programs CALL statement. If the number of data-names 
in each USING phrase are not equal, the OTS issues a diagnostic error 
message and aborts the task. No checks are made to insure that the 
passed arguments are the same size as the expected arguments. It is 
your responsibility to insure that these sizes are compatible. 


Recursive calls to COBOL subprograms are not allowed. If a COBOL 
subprogram contains a CALL statement that directly or indirectly 
causes a subprogram to be re-entered before it has exited from its 
original entry, the OTS will issue a diagnostic error message and 
abort the task. 
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10.4 INCLUDING A NON-COBOL OBJECT MODULE IN A TASK 


Non-COBOL object modules can be combined with COBOL object modules at 
task-build time to produce a single task image. However, you are 
advised to use the same language to write programs that perform I/0 
operations. This note of caution is very important, because, the 
PDP-11 programming languages do not share a common OTS. 


To activate a COBOL subprogram, a non-COBOL calling program must 
contain the equivalent of a COBOL CALL statement. If data is being 
passed to the COBOL subprogram, program register R5 must be set to the 
address of an argument list. The argument list must contain pointers 
to the data being passed. (See Figure 10-2, Argument List Format). 


A non-COBOL subprogram, to be activated by a COBOL program, must 
contain the equivalent of the COBOL PROGRAM-ID statement and the COBOL 
EXIT PROGRAM statement (See Example 1 _ below). If data is being 
passed, the non-COBOL subprogram can access that data via program 
register R5. 


The following sections provide an example of how non-COBOL programs 
can be written for inclusion in a COBOL task image. The MACRO 
programming language is used for the purposes of this example. 


Example 1 - (Calling MACRO Programs from COBOL) 
The format for calling any program from COBOL is: 
CALL literal [USING data-name-l[, data-name-2]...] 


when a MACRO program is being called, literal contains the global 
entry point specified in the MACRO program. If the COBOL program 
contains: 


CALL "BILBO" USING BOFFIN, BOMBUR, BOFUR. 
The MACRO program must contain: 


-GLOBL BILBO 
;entry point - equivalent to PROGRAM-ID 
BILBO: 


RTS PC ;return point - equivalent to EXIT PROGRAM 
If there are any arguments to be passed to the called program (BOFFIN, 


BOMBUR, and BOFUR in this example), these arguments can be accessed 
via program register R5. 
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Example 2 - (Calling COBOL Programs from MACRO) 


When the calling program is a MACRO program, control is passed to’. the 
called program with the following instruction: 


JSR PC,subprogram-name 


Where: Subprogram—-name is the first six characters of the COBOL 
PROGRAM~ID. 


If the MACRO program contains: 


-GLOBL FRODO 


MOV #ARGLST,R5 ;point R5 to argument list 
JSR PC,FRODO ;Ssubprogram call statement 


The COBOL subprogram will contain: 


LINKAGE SECTION. 


- FRODO-ARGUMENTS. 

Ol BOFFIN PIC RS) 
01 BOMBUR PIC X(5). 
01 BOFUR PIC X(5). 


PROCEDURE DIVISION USING BOFFIN,BOMBUR. 


EXIT PROGRAM. 
The MACRO program, in this example, has set R5 to point to the 


argument list expected by the COBOL program. The COBOL OTS will use 
R5 to access the passed arguments. 
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ARGUMENT ADDRESS LIST 
# of arguments R5 must be set 
unused in list (n - 1) to point here 
address of argument #1 


address of argument #2 


address of argument #n - 1 


Figure 10-2 Argument Address List 





CHAPTER 11 


HAND-TAILORING ODL FILES 


This chapter is provided as a guide to those of you who are faced with 
the problem of having to generate ODL files that are compatible with 
either the Merge Utility or the Task Builder. The most common’ reason 
for having to hand tailor an ODL file occurs when non-COBOL programs 
are being merged into a COBOL task image. The information presented 
here is predicated on the assumption that you have read and are 
familiar with the Task Builder Reference Manual that pertains to your 
operating system. The following sections describe the standard ODL 
file as it pertains to PDP-11 COBOL. 


11.1 STANDARD ODL FILE 


The standard ODL file generated by the PDP-11 COBOL compiler consists 
of a header and aé_e body. The header contains information that is 
required to merge one or more ODL files. The body contains ODL 
directives that describe the object program. 


11.2 ODL FILE HEADER 


The ODL file header consists of a Sequence of comment lines. Two are 
required in every ODL file, others are supplied as needed. The 
required comment lines are: 


; COBOBJ =XXXXXX .OBJ 
; COBKER=KK 


Where: 
XXXXXX.OBJ is the name of the object module being described 
KK is the kernel that was used to generate the PSECT 


names for the COBOL program. 
The following comment lines are supplied as needed: 


; COBMAIN This comment line is supplied if the program being 
described is a main program. The absence of this 
line means that the ODL file was generated for a 
COBOL subprogram. 


;RMSSEQ=CIOOXY This comment line is specified if the program 
requires RMS-11 I/O support. One or more lines 
may be supplied. xX and Y represent integer codes 
that respectively specify the file organization 
and operational support required for that 
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organization. File organization is specified by 
the following codes: 


CODE ORGANIZATION 


1 sequential 
2 relative 
3 indexed 


The values allowed for the operational support 
code are meaningful only to future versions of 
PDP-11 COBOL and the Merge Utility. Therefore, 
they are not defined here. 


11.3 ODL FILE BODY 


The ODL file body describes the overlay structure of the COBOL 
program. The body contains the following ODL directive types: 


1. .PSECT defines the name of the code PSECT and makes it 
known to the Task Builder. 

2. NAME defines the name to be assigned to the overlay 
segment by the Task Builder. 

3.  .FCTR describes the contents of the segments. 

4. .ROOT defines the root. 

5. .END informs the Task Builder that the end of the ODL 


file has been reached. 
6.  :comments contains comment entries. 


The .ROOT and .END directives are not supplied by the COBOL compiler. 
They are inserted into the ODL file generated by the Merge Utility. 
If you are generating a stand alone ODL file, these directives must be 
supplied by you. If the ODL file you are generating is to be used as 
input to the Merge Utility, leave these directives out. 


Within a compiler-generated ODL file, the directives .PSECT, .NAME, 
and .FCTR are generated around the PSECT kernel. If the PSECT name 
kernel for a given program is KK, the format of the names generated in 
the ODL file is: 

Entity Format of Name 

~PSECT SKKMMM 

-NAME KKS$ MMM 

-FCTR KKMMM$ 
Each .PSECT defined in the ODL file begins with a $ followed by the 
two character kernel (SKK). Each .NAME directive begins with the two 


character kernel followed by $ (KKS$). Finally, each .FCTR directive 
begins with the two-character kernel and ends with a $ (KKMMMS). 
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11.4 COMPILER-GENERATED ODL FOR COBOL PSECTS 


The following sections discuss the ODL directives generated for 
different types of overlay requirements. The characters NNN when used 
in examples refer to the three character suffix generated by the 
compiler for each PSECT. The characters KK refer to the kernel 
characters that make the PSECT unique to a particular compilation. 


11.4.1 ODL Generated for Overlays Containing Only One PSECT 


For overlays containing only one PSECT, the following lines are 
generated: 


.PSECT SKKNNN ,GBL,RW,CON,I1 
. NAME KKSNNN ,GBL 
KKNNNS .FCTR * KKSNNN-SKKNNN 


11.4.2 


(o) 


DL Generated for Overlays Containing More Than One PSECT 


For each overlay that contains more than one PSECT, a .PSECT directive 
is generated for each PSECT in the overlay. These .PSECT directives 
are followed by a .NAME and .FCTR directive. Consider the following 
example. 


Example 
Two PSECTs, SAA001 and $AA002, are to be placed in the same overlay. 
The segment-number assigned to the PSECTs is 20. The following ODL 


directives are generated: 
; DEFINE PSECT SAA001 
-PSECT $AA001,GBL,RW,CON,I 
; DEFINE PSECT $AA002 
-PSECT $AA002,GBL,RW,CON,I 
;DEFINE THE OVERLAY NAME 
- NAME AAS020,GBL 
;DEFINE OVERLAY CONTENTS 


AA020S: .FCTR *AASO020-SAA001-SAA002 


11.4.3 ODL Generated for All Overlayable PSECTS 


All .FCTR directives that describe the overlayable PSECTsS must be 
collapsed into one final .FCTR directive. This directive describes 
the entire overlayable portion of the object code. The name 
associated with this .FCTR directive is derived from the two-character 
kernel assigned to the PSECTs. If the kernel is KK, then the name of 
the .FCTR directive that describes the entire overlayable part of the 
object code is KKOVRS. 
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The following example shows how the KKOVRS factor is developed for 
various overlay configurations: 


Example 1: All Code Psects Overlay One Another 


-PSECT $AA001,GBL,RW,CON,I 
.NAME AAS$001,GBL 

AAOO]: .FCTR *AASOO1-SAAOOL] 
.PSECT $AA002,GBL,RW,CON,I 
NAME AA$002,GBL 

AA002S: .FCTR *AAS002-SAA002 
; 
.PSECT $AA003,GBL,RW,CON,I 
.NAME AAS003,GBL 

AA0O3S: .FCTR *AAS003-SAA003 
.PSECT $AA004,GBL,RW,CON,I 
. NAME AAS004,GBL 

AAOO4S: .FCTR *AASO04-SAA004 
.PSECT $AA005,GBL,RW,CON,I 
.NAME AAS005,GBL 

AAOOSS: .FCTR *AASO05-SAA005 


7IN THIS EXAMPLE, ALL PSECTS OVERLAY 
:ONE ANOTHER. 


AAOVRS: .FCTR (AA001S ,AA002S ,AA0N03S ,AA004S ,AA004S ,AA005S) 
Example 2: Two Code Psects Are in the Same Overlay 
.PSECT S$AA001,GBL,RW,CON,I 
.PSECT $AA002,GBL,RW,CON,I1 
. NAME AAS001,GBL 
AAOOIS: .FCTR *AAS001-SAA001-SAA002 
.PSECT $AA003,GBL,RW,CON,I 
. NAME AAS003,GBL 
AA003S: .FCTR *AAS003-SAA003 
.PSECT $AA004,GBL,RW,CON,I 
. NAME AAS004,GBL 
AAOO4S: .FCTR *AAS004-SAA004 
.PSECT $AA005,GBL,RW,CON,I 
. NAME AAS005,GBL 
AAOOSS: -FCTR *AAS005-SAA005 
AAOVRS: -FCTR AAOO1S ,AA003S ,AA004S ,AAN05S 


Example 3: Two Occurrences of Two Psects in the Same Overlay 


;IN THIS EXAMPLE, PSECTS S$AAQ01 AND SAA002 
;ARE IN THE SAME OVERLAY. PSECTS SAA003 
;AND $AA004 ARE IN THE SAME OVERLAY. 


;PSECT $AA005 IS IN AN OVERLAY ALL BY ITSELF 


;PSECT $AA001,GBL,RW,CON,I 
;PSECT $AA002,GBL,RW,CON,I 
- NAME AAS$001,GBL 
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AAOOIS: .FCTR *AASO01-SAA001-SAA002 
+PSECT $AA003,GBL,RW,CON,I1 
.PSECT $AA004,GBL,RW,CON,1 
“NAME AAS003,GBL 

AA003S: .FCTR *AAS003-SAA003-SAA004 
.PSECT $AA005,GBL,RW,CON,I1 
.NAME AA$005,GBL 

AAOOSS: sFCTR *AAS005-SAA005 

AAOVRS: .FCTR AA001S$ ,AA003$ ,AA005$ 


11.5 MERGING STANDARD ODL FILES 


To develop an ODL file for a task composed of more than one COBOL 
object program, it is necessary to merge the ODL files for each 
individual object program into a single ODL file that describes’ the 
overlay requirements for the task. 


zA11 Amr 


All of the ODL files to be merged are partial ODL files. That is, 
none of these ODL files can be submitted directly to the Task Builder 
to build a task; because, none of the compiler generated ODL fiies 
contain a .ROOT directive. The .ROOT directive that describes the 
task is supplied by the Merge Utility. 


11.6 INCLUDING NON-COBOL PROGRAMS IN A TASK 


To use the Merge Utility to include a non-COBOL object module in a 
task image, you must: 


l. Create a standard COBOL ODL file (use any text editor) 


2. Specify this ODL file as input to the Merge Utility. 


11.6.1 Creating a Standard COBOL ODL File 


A standard COBOL ODL file for a non-COBOL object module contains one 
or two directive lines: 


1. Object Program ID Line - This line is required. It 
identifies the object module to be included in the task 
image. The format of this line is: 

+ COBOBJ =XXXXXX .OBJ 


Where XXXXXX.OBJ is the name of the object module to _ be 
included in the task image. 


Pi 
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2. Main Program ID Line - This line is present only _ for 
non-COBOL object modules that are main programs as opposed to 
being subprograms. The format of the line is: 


; COBMAIN 


For each invocation of the COBOL ODL Merge Utility, one and only one 
main program ODL file can be specified. If no main program ODL file 
is specified, the Merge Utility continues to request more input until 
a main program ODL file is specified. If more than one main program 
ODL file is specified, all but the first is rejected, and appropriate 
diagnostic error messages are issued. Consider the following 
examples. 


Example 1 

MACRO program START.OBJ is a main program in a task consisting of a 
main program and several subprograms. The ODL file to be 
hand-generated is: 


; COBOBJ=START.OBJ 
; COBMAIN 


Example 2 

Macro subprogram SUBX.OBJ is to be part of a task image that consists 
of several COBOL subprograms and a COBOL main program. The ODL file 
to be hand-generated is: 


; COBOBJ=SUBX .OBJ 


11.7 REARRANGING A COMPILER-GENERATED ODL FILE 


The ODL file generated by the compiler can be rearranged to modify the 
overlay structure of a task. If the ODL file describes a task that 
has overlayable segments, one or more of these segments can be 
converted into non-overlayable segments by: 


1. Modifying the compiler-generated ODL file. 


2. Specifying a one-line Task Builder option at task-build time 
for each segment made non-overlayable. 


11.7.1 Modifying the Compiler-Generated ODL File 


Modifying the compiler generated ODL file requires the following 
steps: 


1. Each overlayable segment is named in the ODL file by an ODL 
-NAME directive. This .NAME directive must be removed. 


2. Each name appearing in a .NAME directive is marked with an * 
and placed as_ the first element of a .FCTR directive. For 
each .NAME directive removed by step 1, this .FCTR directive 
must be removed. 
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3. All references to the name of the .FCTR directive removed in 
step 2 must be removed from the ODL file. 


4. All PSECTs referenced in the .FCTR directive that was removed 
in step 3, must be removed from the ODL file. 


Example 
The task image contains three overlayable segments, CS$$010, cCS$$015, 


and css020. Segment C$$020 is to be forced into the root. Figure 
11-1 contains a listing of the merged ODL file. 





;MERGED ODL FILE CREATED ON 26-JAN-77 AT 10:50:00 
;COBOL STANDARD ODL FILE GENERATED ON: 26-JAN-77 10:48:37 
; COBOBJ=TEST1 .OBJ 
; COBKER=C$ 
; COBMAIN 
-NAME C$$010,GBL 
-PSECT $CS$003,GBL,1,RW,CON 
C$010$: .FCTR *C$$010-$CS003 
-NAME C$$015,GBL 
-PSECT $C$004,GBL,1,RW,CON 
C$015$: .FCTR *C$$015-S$CS$004 
-NAME CS$020,GBL | 
.PSECT $C$005,GBL,1I,RW,CON 
C$020$: .FCTR *C$$020-$C$005 | 
CSOVRS: .FCTR C$010$ ,C$015$ ,C$020$ 
1 


CBOBJ$: .FCTR TEST1.OBJ 

CBOVRS: .FCTR CSOVRS 

CBOTS$: .FCTR [320,13] COBLIB/LB 
RMSS: -FCTR [1,1]RMSLIB/LB 


OBJRTS: .FCTR CBOBJS-CBOTSS-RMSS 


-ROOT OBUJRTS-—(CBOVRS) 


Figure ll-l Merged ODL File Listing 


To force segment C$$020 into the root, the merged ODL file must be 
modified as follows: 


l. The .NAME directive referencing C$$020 must be removed. . 
2. The .FCTR directive containing *C$$020 must be removed. 


3. All references to the PSECTs in the removed .FCTR directive 
must be removed. 
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Figure 11-2 contains the ODL listing after the modifications have 
been made. 


»>MERGED ODL FILE CREATED ON 26-JAN-77 AT 10:55:22 
:COBOL STANDARD ODL FILE GENERATED ON: 26-JAN-77 
: COBOBJ=TEST1 .OBJ 

: COBKER=C$ 

; COBMAIN 


-NAME CS$$010,GBL 

-PSECT $C$003,GBL,1,RW,CON 
c$010$: .FCTR *C$$010-$CS003 

-NAME CS$$015,GBL 

-PSECT $CS004,GBL,1I,RW,CON 


c$015$: .FCTR *CS$$015-$CS004 
CSOVRS: .FCTR C$010$,C$015$ 
CBOBJS$: .FCTR TEST1.OBJ 
CBOVR$: .FCTR CSOVRS 
CBOTSS: .FCTR [1,1] COBLIB/LB 
RMSS: .FCTR [1,1] RMSLIB/LB 
OBJRT$: .FCTR CBOBJ$-CBOTSS-RMS$ 
-ROOT OBJRTS- (CBOVRS) 
.END 





Figure 11-2 Modified ODL File 


11.7.2 Specifying Task Builder Options 
For each overlayable segment made non-overlayable, a GBLDEF Task 
Builder option must be specified at task-build time. The format of 
the option is: 
GBLDEF=KK$MMM:0 
Where: 
KKSMMM is the name of the segment that is being made 
non-overlayable. (This is the name in the .NAME ODL 
directive that was deleted when the ODL file was modified). 
Consider the following example. 
Example 
To make the overlayable segment (C$$020) described in the example in 
Section 11.7 non-overlayable, enter the following in response to the 
Task Builder ENTER OPTIONS prompt: 


GBLDEF=C$$020:0 (ur ) 


vy) 
ray 


Figure 11-3 shows the overlay description of the task image before 
after segment C$$020 was made non-overlayable. 
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| BEFORE | 


TESTI .TSK#F1 MEMORY ALLOCATION MAP TKB M27 
26-JAN-77 10:51 


PARTITION NAME : GEN 

IDENTIFICATION : 026108 

TASK UIC : [320,4] 

STACK LIMITS: 000176 001175 001000 00512. 
PRG XFR ADDRESS: 022514 

TOTAL ADDRESS WINDOWS: 1. 

TASK IMAGE SIZE : 6880. WORDS 

TASK ADDRESS LIMITS: 000000 032657 


TEST1.TSK;1 OVERLAY DESCRIPTION: 


| BASE TOP LENGTH 

| 000000 032507 032510 13640. TEST 
032510 032607 000100 00064. C$$010 3 overlayable 
032510 032657 000150 00104. C$$015 
032510 032617 000110 00072. C$$020 segments 


AFTER 





i 

| 

| TEST2 .TSK;2 MEMORY ALLOCATION MAP TKB M27 
‘26-JAN-77 10:57 





PARTITION NAME : GEN 

IDENTIFICATION : 026108 

TASK UIC : [320,4] 

STACK LIMITS: 000176 001175 001000 00512. 
PRG XFR ADDRESS: 022514 

TOTAL ADDRESS WINDOWS: 1. 

TASK IMAGE SIZE : 6912. WORDS 

TASK ADDRESS LIMITS: 000000 032743 


TEST2.TSK;2 OVERLAY DESCRIPTION: 


BASE TOP LENGTH 


000000 032573 032574 13692. TESTI 
032574 032673 000100 d0064. C$$010 2 overlayable 
032574 032743 000150 00104. C$$015 segments 





Figure 11-3 Overlay Description Map Before and After Modification 
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ERROR MESSAGES 


12.1 COMPILER SYSTEM ERRORS 


The PDP-1l COBOL compiler is a complex system program consisting of 
many program overlays that manipulate numerous data structures. 
Throughout the compiler, consistency checks are performed on program 
flow and the contents of data fields. If the compiler detects an 
inconsistency, it types a message on the console and terminates’ the 
compilation. A system error message has the following format: 


SYSTEM ERROR NNNNN 


where NNNNN is a number used by the DEC COBOL developers to determine 
the probable cause of the error. When a system error occurs, the 
compiler's input file is closed and all output files (object, list, 
and ODL) are closed and deleted. 


In the event of a PDP-11 COBOL compiler system error, contact your DEC 
Software Support Specialist immediately. 


12.2 DIAGNOSTIC ERROR MESSAGES 


Appendix H contains a numerical listing of the diagnostic messages 
generated by the PDP-11 COBOL compiler. The compiler generates these 
messages whenever it detects an error in the source program. In 
general, a source error detected by the compiler results in the 
associated diagnostic message being embedded in the source program 
listing. That is, when an error is detected in the source program, 
the compiler prints the diagnostic message either before or after the 
erroneouS source program line. There are two exceptions to the 
general concept of "embedded diagnostics": 


l. There may be diagnostic messages listed after the last entry 
in the Data Division and before the Procedure Division 
header. These are diagnostics which logically cannot be 
issued until the entire Data Division text is processed. 


2. There may be diagnostic messages listed after the last line 
of the Procedure Division. These are diagnostics which 
logically cannot be issued until the entire Procedure 
Division text is processed. 
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In addition to the error message number and message text, the display 
contains a source line number, which identifies the error line, and an 
alphabetic code (discussed below) which informs you of the seriousness 
of the error. The information in a diagnostic message line is 
displayed (from left to right) in the following order: 


1. Alphabetic code, 

2. Source line number, 

3. Numerical error number, 

4. Text of the diagnostic message. 
For convenience, the alphabetic code is left-justified in the listing 
so you merely scan the listing to identify any diagnostic message 
issued during compilation. Again, for your convenience, a summary of 
the number of errors detected during the compilation is given at the 
end of the source listings. If no errors are detected during the 
compilation, the compiler prints "NO ERRORS" at the end of the source 
listing. 


The following illustration shows a typical diagnostic message and the 
Manner in which it appears on the source listing: 


COBOL 4.99 SRC:MAP.CBL;9 g5-NOV-78 18:49:18 PAGE 993 


GBGI6 MOVE TMP-AMT TO HIGH-AMOUNT. 

GOG97 IF HIGH-AMOUNT NOT = HIGHEST-AMT DISPLAY "ERR 19". 
GAB98 ig | 

8999 MOVE TMP-AMT TO NEW-AMT. 


I $9899 372 POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. 


$019B IF NEW-AMT NOT = OLD-AMT DISPLAY "ERR 11". 
$191 . 

GG1G2 MOVE NEW-AMT TO NEXT-AMT. 

$9163 IF NEXT-AMT NOT = MIN-AMT DISPLAY "ERR 12". 
PP1p4 * 


In the example, the diagnostic message is immediately identified by 
the appearance of the left-justified alphabetic code I. The 
alphabetic code indicates that the message is an I-type 
(informational) diagnostic; the diagnostic is issued for source line 
number 99; the error number is 372; and the text of the message is 
POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. Note that the 
diagnostic message line, in this example, appears after the source 
line for which it was issued. 


The error messages, used in conjunction with this chapter, provide you 
with an important debugging tool. This chapter contains information 
necessary for interpreting the messages. It explains what caused the 
error and how the compiler handled the error. 


ERROR MESSAGES 


Since different errors cause varying degrees of problems for the 
compiler (some do not affect the compilation at all, while others may 
be so critical that they cause an abort of the compilation), the 
PDP-11 COBOL compiler provides four general types (or severity levels) 
of diagnostic messages. Alphabetic codes (I, W, F, and A) identify 
these error levels. When it detects an error in the source program, 
the compiler attempts to recover from the error and continue to 
compile the program. This recovery action may force the compiler to 
make an assumption about the source program. The four levels of 
diagnostic messages are categorized according to the likelihood that 
the result of the compiler's assumption will be an object program that 
runs as originally intended by the programmer. 


The following list explains the purpose of and the compiler's action 
for each of the four message levels: 


I (Informational) Informative diagnostic. The purpose of such 
a diagnostic is to convey information to you in an 
observational or advisory capacity. The compiler's error 


recovery (if any is required) is almost certain to follow 
your intent. 


W (Warning) Warning diagnostic. The purpose of this type of 
message is tc warn you that something is wrong with the 
associated source statement, but that the compiler can take 
corrective action on the source element in error. The 
compiler's recovery action may not agree with your intent, 
but the statement, as corrected by the compiler, will be 
executable. 


F (Fatal) Fatal diagnostic. The purpose of such a_ diagnostic 
is to indicate to you that something is fatally wrong with 
the indicated source statement. By fatal, the compiler 
means it cannot generate the object code required for the 
functionality the programmer coded in the erroneous’ source 
statement. The compiler's error recovery action will 
probably leave out a portion of the source program. In 
general, the compiler will not produce an object program for 
COBOL source programs that have F-type errors in them. 
However, you can force the compiler to generate an object 
program by specifying the /ACC:2 switch in the command 
string input to the compiler prior to compilation (See 
Section 2.3.2, Compiler Switches, for a detailed explanation 
of the /ACC:n switch.) The /ACC:2 switch causes the compiler 
to generate an object program, even if the source program 
contains F-type errors. When the object program is 
executed, it can fail when it attempts to execute code 
generated as a result of the fatal, but accepted, error. 
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WARNING 


When you specify the /ACC:2 switch, you formally 
acknowledge that you are willing to let the program 
go into execution even though it may have fatal 
errors in it. Because the source program has very 
severe errors in it, the behavior of the associated 
object program is, in general, unpredictable. In 
certain cases, such as a COBOL program with files 
opened in I-O mode, letting the program with F-type 
errors go into execution could cause undetected 
Serious errors, such as damage to files. Therefore, 
the /ACC:2 switch should be used with caution. The 
facility is provided as an extra debugging option. 
It can be useful in shortening the compile-debug 
cycle, particularly if applied to large COBOL 
programs which take considerable compilation time. 


(Abortive) Abortive diagnostic. The purpose of this type of 
diagnostic is to inform you that the compiler must abort 
compilation. The compiler's error recovery is not possible: 
it can make no valid assumptions and has no choice but to 
abort the compilation. 


12.3 RUN-TIME FILE I/O ERROR PROCEDURES 


When an error condition occurs during I/O operations, the following 
procedure is used: 


1. 


If the file status key for the file is present, it is set to 
the appropriate code for the error condition. Appendix C of 
the PDP-11 COBOL Reference Manual lists file status’ key 
values. 


If an AT END or INVALID KEY imperative condition is specified 
for the I/O operation, the path indicated by the imperative 
Statement is taken. The file system performs no other 
processing in the file for the current statement. The USE 
procedure, if one is declared for the file, is not performed. 


If no AT END or INVALID KEY imperative condition is specified 
for the I/O operation and a USE procedure is declared for the 
file, the USE procedure section is performed, and _ then 
control is returned to the program. The file system performs 
no further processing for this file. 


If no USE procedure is declared for the file, a fatal error 
condition exists; the OTS aborts the program and displays an 
I/O error message. In the following example, RMS failed to 
find the specified file. Having no USE procedure to execute, 
the OTS displays the message: 


CBL -- 17: OPEN ERROR USING FILE (ACCTG.DAT) 
ASSOCIATED RECORD SERVICES ERROR: -736 (-26) 
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NOTE 


The OTS does not display an I/O error 
message if it executes a USE procedure. 
However, if the program executes a STOP 
RUN statement in the USE procedure, the 
OTS displays the error message as if no 
USE procedure existed. 


The OTS error messages are listed and described in Appendix J; 
Appendix I describes the Record Management Services error messages. 
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Wherever it can, the COBOL OTS will list auxiliary information along 
with the error message: 


PROGRAM-ID. The OTS displays the first six characters of the 
program-name in the PROGRAM-ID paragraph. 


IDENT. Refers to the identification number that the compiler 
assigned to the program compilation. IDENT appears at the 
beginning of the compiler listing. 


PSECT. Refers to the PSECT that was being executed when the 
OTS detected the error. PSECT names are found in the 
Procedure Map on the compiler listing. 


OFFSET. Specifies the octal byte offset from the beginning 
of the PSECT. Offset locations appear on the compiler 
listing if the /OBJ switch is used when the program is 
compiled. 


NESTED PERFORM SOURCE LINE NUMBERS. If the program was 
executing one or more PERFORM statements when the error 
occurred, the OTS lists the source listing line numbers of 
each PERFORM statement to help you locate the error. 
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CHAPTER 13 


CCBOL INTERACTIVE DEBUGGER (CID) 


This chapter describes the use of the COBOL Interactive Debugger 
(CID), which is an interactive aid that you can include in your 
program during the merge or task-build process. The chapter concludes 
with a sample CID debugging session and a COBOL programming example. 
By using CID, you can: 

@e Examine and change data in your program 


@e Set, show, and cancel breakpoints 


e Control program flow 


CID allows you to find program errors without recompiling or changing 
your program. To use CID, you need only task-build the program with 
the CID module, then run it. 

NOTE 


In this chapter's examples, system 
responses are underlined. 


13.1 HOW TO INCLUDE CID 

All CID references to your program are in terms of program name, 
segment, and offset. A simple way of getting this information is to 
specify the /MAP and /OBJ switches when you compile your program. 
Follow this procedure to generate programs with CID: 


1. Produce a listing and specify the /MAP and /OBJ switches when 
you compile your COBOL program. 


2. Print the listing and keep it for the debugging session. 
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Lee) 


Task-build your program. Place the CID module specifier 
before the COBLIB specification in the command line. If you 
use the MERGE utility, you can include CID then. 


For example: 


RSTS/E: TKB> PROG=PROG,LB:CID,COBLIB/LB 


RSX-11M: TKB> PROG=PROG,[1,1]JCID,COBLIB/LB 


IAS: LINK PROG,LB:[1,1]CID,LB:[1,1]JCOBLIB/LIBRARY, 


RMSLIB/LIBRARY 


If you use the MERGE utility, respond to the following 
question as shown: 


DO YOU WANT TO INCLUDE THE COBOL DEBUGGER (CID)? 
PLEASE ANSWER YCES) OR N(O): YES 


4, Execute the program. CID takes control and prompts you for 
input with: 


CID> 


NOTE 


Including CID adds about 1@@@ (decimal) 
words to your program's memory address 
space requirement. If the increase 
exceeds the program's Size limit, 
recompile it (for debugging purposes 
only) with the /OV switch. 


13s2 COMMAND MODE AND THE CID ENVIRONMENT 


CID is in command mode when the debugger is waiting for your’ input 
(displaying the prompt CID>). When your program is in CID command 
mode, the current location (segment) is called the CID environment. 
The environment consists of the program name and segment number, 
where: 


1. Program name refers to the name in the PROGRAM-ID paragraph 
in the main program or called program. 


2. Segment number refers to the segment within the named 
program. 


Except for SET BREAKPOINT an 
the current environment. Y 
current program (with the ex 


d CANCEL BREAKPOINT, commands effect only 
Ou can examine and change data only in the 
ception of linkage parameters). 


When you run a program that includes CID, the initial environment is 
segment @1 of the main program, and CID is in command mode. The 
environment changes only as the program executes. Therefore, to gain 
control of CID in a different environment, you can set breakpoints and 
continue execution; CID returns to command mode when it reaches’ the 
breakpoint. 
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lov ADDRESSING 


Several CID commands refer to data or code locations in your’ program. 
The following sections describe the different methods of addressing 
data and code. 


T3636 Addressing Data 


The compiler generates data descriptors for all Data Division items 
that you reference in Procedure Division statements. The OTS accesses 
data items by using information in the descriptors. A DATA address is 
an octal number that specifies the relative location of the data 
descriptor. You find these addresses in the "DIR LOC" column on _ the 
data map listing. 


Linkage Section items are addresses prefixed with the letter "L" on 
the data map listing. Because the compiler assigns addresses for the 
Linkage Section differently than it does for other Data Division 
sections, you must use the /LINKAGE option to reference them. 


You cannot reference items marked on the data map with "####%" jn 
place of an address. Asterisks indicate that you did not reference 
the item in the Procedure Division and that the compiler, therefore, 
did not generate a data descriptor. 


Reference table items by following the address with a list of 
subscripts enclosed in parentheses. Specify subscripts as unsigned 
decimal integers, and separate multiple subscripts with commas, as you 
would in a COBOL statement. 


Examples: g 

56 

14(9) 

28(23,12) 
The first two examples reference data items whose data descriptors are 
located at octal @ and 56. The third reference specifies the ninth 
occurrence of the table item whose data descriptor is located at octal 
address” 14. The last example specifies a multiply-subscripted data 


item whose data descriptor is at octal address 20; the subscripts are 
written exactly as they would be in a COBOL statement. 


13332 Addressing Procedure Division Code 
Procedure Division code addresses have three parts: 
1. Program name 
2. Segment number 
3. Octal offset in the segment 


For example, the address PROGA:2,6 refers to offset location 6 in 
segment 2 of the program named PROGA in its PROGRAM-ID paragraph. 


13-3 


COBOL INTERACTIVE DEBUGGER (CID) 


In some commands, the program name and the segment number’ are 
optional. However, if you specify the program name, you must also 
specify the segment number. If you omit the program name, but specify 
the segment number, the colon (:) is required. 


Examples: PROGA:2, 16 
refers to program PROGA, 
segment 2, offset 16 


O96 
refers to segment 3, 
offset 32 in the 
current program 


refers to offset 6 in the 
current environment 


The program listing contains the address for each verb in the 
Procedure Division on the program listing if the /OBJ switch was used. 
In the following extract from a listing for program PROGA, the full 
address of the MOVE statement is PROGA:5,7@. 


IF > @5 888854 
MOVE >: 85 @G80070 
08395 IF A = B MOVE B TO C. 


13.4 COMMANDS 


CID commands consist of words, numbers, alphanumeric strings and _ the 
Special characters: 


left parenthesis 
) right parenthesis 
period (decimal point) 
comma 
minus sign 
equal sign 
: colon 
/ slash or stroke 


“tot 


Use upper-case letters to enter command and option words; and 
separate the items of each command by one or more spaces or tab 
characters. 


You can abbreviate command and option words to a single letter. 
Because CID interprets only the first letter of each word, it accepts 
misspellings. 
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These CID commands are discussed in the following sections: 


CANCEL BREAKPOINT Unmark a stop location 


DEPOSIT Change the value of a data item 
EXAMINE Display the value of a data item 
GO Control execution path 

SET BREAKPOINT Mark a location to stop execution 
SHOW BREAKPOINTS Display active breakpoints 

XIT Terminate debugging session 


13.4.1 CANCEL BREAKPOINT Command 


Format: CANCEL BREAKPOINT <code address> 


Use this command to cancel or remove a breakpoint that was set at the 
specified <code address>. 


CID displays the following message after it cancels the breakpoint: 
CAN <program name> : <segment number> <offset> 


Examples: CID> CANCEL BR 6 
Cancels the breakpoint at 
location 6 in the current 
segment of the current 
program. 


CAN PROGA : @1 @B88GB6 


CID> C B PROGB :3,42 

= Ss Cancels the breakpoint at 
location 42 in segment @3 
of program PROGB. 


CAN PROGA : 83 @BBGH2 
CID? 


13.482 DEPOSIT Command 


Format: DEPOSIT [/LINKAGE] <data address> = <value> 


Use this command to replace the value of the addressed data item with 
a new value. 


For numeric items, enter <value> as a-decimal number. You can include 
a decimal point and leading minus’ sign. The OTS moves the value 
according to the COBOL rules for the MOVE statement. Therefore, 
decimal alignment, truncation, and other formatting occur as specified 
by the data description. 
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For alphanumeric, alphabetic, group, and all edited items, enter 
<value> as an alphanumeric literal (enclosed in quotes). The OTS 
moves the literal according to the COBOL rules for a group move. 


Use the /LINKAGE option to deposit values into data items in the 
Linkage Section of your program. 


You cannot DEPOSIT values into index data items. 
Examples: CID> DEPOSIT 6=1.34 


1.34 

CID> D 12(3) =-15 
-15 

CID> DE. 126="HELLO" 
ELLO 

CID> DG=6 


= 





QS 


ID> 





CID displays the new value of the data item after a DEPOSIT operation. 
You can then confirm that the change is correct without using an 
additional EXAMINE command. For example, if the picture of the item 
is X(5) and you enter: 


CID> DEPOSIT 42="SYSTEM" 


CID displays: 


~ 


YSTE 





and you -see immediately that truncation occurred. 


13.4.3 EXAMINE Command 


Format: EXAMINE [/LINKAGE] <data eddress> 


Use the EXAMINE command to display the value of the addressed data 
item. CID displays numeric items as _ numeric values with decimal 
points and (for negative values) leading minus’ signs. It displays 
alphanumeric items, such as alphabetic or edited, as strings of ASCII 
characters, with non-printable characters displayed as "?". 


Use the /LINKAGE option to display data items located in the Linkage 
Section of your program. 


Examples: CID> EXAMINE 1@4 
185.6 


5. 
CID> EX 142 
NEW HAMPSHIRE 
CID> E 12(3,5) 
= 
i 


(oa) 


Qa 
oO 


> EX/L 220 


ale 


ID 


Vv 
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13.4.4 GO Command 


Format: GO [<offset>] 


Use the GO command to resume execution of your. program. Specify 
<offset> to continue execution at a different location in the current 
segment. Otherwise, execution continues at the next instruction. 
Remember that you can continue execution only in the current 
environment. 


CID does not confirm that a valid instruction exists at the specified 
offset; therefore, the result of specifying an incorrect offset is 
unpredictable. CID also does not reset PERFORM exits; therefore, 


using the GO command to leave an active PERFORM can result in a later 
error. 


13.4.5 SET BREAKPOINT Command 


Format: SET BREAKPOINT <code address> 

Use this command to set a breakpoint at <code address>. 

Up to ten breakpoints can be active at one time. If all ten 
breakpoints are active, CID displays an error prompt when you type 


this command. To set a new breakpoint when ten are active: 


1. Use the SHOW BREAKPOINTS command to display the active 
breakpoints. 


2. Use the CANCEL BREAKPOINT command to remove breakpoints’ that 
you no longer need. 


3. Set the new breakpoint. 
CID displays the following message when the breakpoint is set: 


SET <program name> : <segment number> <offset> 


If your program later reaches the breakpoint, CID displays: 
AT: <program name> : <segment number> <offset> 
It then waits in command mode for a new entry. 


Examples: CID> SET BREAKPOINT 26 
Sets a breakpoint at location 26 
in the current segment of the 
current program. 


SET PROGA : 62 ®G8G26 


CID> S B PROGA:3,1422 
Sets a breakpoint at location 1422 
in segment 3 of program PROGA. 


SET PROGA : @3 @@1422 
CID> 
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13.4.6 SHOW BREAKPOINTS Command 


Format: SHOW BREAKPOINTS 


Use SHOW BREAKPOINTS to display the list of active breakpoints and the 
location of the current breakpoint. 


Notice that this command looks the same to CID as SET BREAKPOINT 
without a code address, since CID interprets only the first character 
of each word. 


Examples: CID> SHOW BREAKPOINTS 
BP: PROGA : @1 @8@90826 
BP: PROGA : @3 @@1422 
BP: SUBR  : @7 @G8184 
AT: SUBC : @2 @@0062 
CID> 3 B 


—— ee 


CID> 


(same as above) 


13.4.7 XIT Command 


Format: XIT 


Use this command to end the execution of your program and _ the 
debugging session as if your program executed a STOP RUN statement. 


335 PROGRAM INITIATION 
When your program begins, it automatically enters CID command mode as 
if you had set a breakpoint before the first instruction. However, 
CID cancels this breakpoint automatically when you enter any valid 
command. 
Use this automatic breakpoint to: 

1. Examine or change data before your program begins. 


2. Set breakpoints for use later in the debugging session. 


3. Begin execution at a different location. 
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13.6 USING BREAKPOINTS 


CID suspends execution of your program and returns to command mode 


when your program reaches a breakpoint. 


Set breakpoints at significant locations so you can: 


Tis 
e. 


3. 


Examine data to verify correctness. 
Change data to correct values. 


Change data or continue execution at another location to test 
a theory that explains incorrect results. 


Before you transfer control, analyze your program's current status’ to 


be sure 


that the transfer will not leave an active PERFORM. 


Otherwise, the OTS will terminate your program's execution if it 


detects an improperly nested PERFORM because the old PERFORM is still 
active. 
Taf ROGRAM TERMINATION AND SUSPENSION 


Program execution can be terminated in three ways: 


Re 


You can terminate both your program and the debugging session 
by: 


e Using the XIT command during command mode 


e Typing a termination control character, 
such as “C 


The OTS suspends execution of your program when it detects an 
error. It displays an error message and returns control to 
CID. CID then displays the following message and enters 
command mode: 


AT: <program name> : <segment number> 177777 
CID> 


Although the CID message does not indicate the location of 
the error, you can find it in the OTS error message. You can 
continue execution by using the GO command with a new 
location, provided it is in the same environment in which the 
error occurred. Before transferring control, you may want to 
use other CID commands to examine or change data, or to set 
breakpoints. CID terminates the debugging session if you 
enter’ a GO command without a location. 


The OTS suspends program execution when it executes a STOP 
RUN statement. It returns control to CID, as described 
earlier; the OTS error message does not appear’ since no 
error condition exists. You can terminate the session or 
continue execution as just described. 
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13.8 CID Command Errors 


When CID detects an error in a command entry, it sounds an alarm 
(using the BELL character) and displays the prompt: 


? 
CID> 





Although more specific error reporting would be useful, it was omitted 
to minimize your program's memory requirement when you request the Ci 
module. 
Some errors that frequently occur are: 

1. Typing a non-existent command, such as a "Z"., 


2. Typing a command in lower case, such as "go". (You must’ use 
upper case.) 


3. Forgetting to enter the colon when you intend to specify the 
current program name in a code address, such as "S B 5,6". 
The correct command would be "S B :5,6". 

4. Forgetting to leave a space between multiple-word command 
words, such as typing "CB" instead of "C B" to abbreviate 
"CANCEL BREAKPOINT". 


5. Omitting the second word in two-word commands, such as 
entering "CANCEL" instead of "CANCEL BREAKPOINT". 


6. Omitting the equal sign in a DEPOSIT command. 


7. Omitting quotes in a DEPOSIT ‘command that refers to a 
non-numeric data item. 


8. Trying to DEPOSIT a non-numeric value into a numeric data 
item. 


9. Trying to DEPOSIT a value into an index data item. 

18. Trying to set more than ten breakpoints. 

11. Specifying an invalid offset. 

12. Trying to continue execution in a non-current environment. 
13. Forgetting to use the /LINKAGE option in the EXAMINE and 


DEPOSIT commands when trying to reference data items located 
in the Linkage Section. 
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13.9 EXAMPLES 


This section contains an annotated debugging session that demonstrates 
the use of many CID features. Following it are sample listings of a 
COBOL program (TESTA) and a subprogram (TESTB); the debugging session 
references these listings. 


Program TESTA accepts a character string from the terminal and passes 
it to TESTB. TESTB reverses the character string and returns it (and 
its length) to TESTA. 


13.931 Sample Debugging Session 


The following debugging session does not demonstrate the location of 
actual program errors; it is designed to show the use of CID 
features. The session begins immediately after the RUN command is 
entered: 


1) We get control before execution of the 
first COBOL statement in the program. 


2) Now, we set a breakpoint in program 
TESTB just after it determines’ the 
length of the string. CID confirms that 
the breakpoint was set. 
CID> SET BREAKPOINT TESTB: 1,164 
SET TESTB : @1 900164 
3) We also set a breakpoint in TESTA just 
before it calls TESTB. Note that the 
abbreviation "S B" is sufficient, as is 
"SET B" in a later command. 


A: 61 @88GH6 
4) We set a third breakpoint just before 
TESTB displays the string length 
(DISP-COUNT). Note that the colon is 
required before the segment number. 
CID>SET B :2,34 
SET TESTA : @2 G@88G34 
5) We change the value of LETTER-COUNT. 
CID displays the value it stored; note 
that the value was truncated because the 
PICTURE of LETTER-COUNT specifies only 
two digits following the assumed decimal 
point. 
CID> ‘DEPOSIT @ -= 1.836 
T. 83 
6) We attempt to DEPOSIT a numeric value 
into INPUT-WORD (an invalid operation). 
CID responds by sounding an alarm (using 
the BELL character) and displaying a 
question mark. 
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CID> GO TESTB: 1,6 
oes 


CID> GO 
ENTER WORD 


NOW IS THE TIME 
AT: TESTA G1 OGOBH6 


CID> EXAMINE 6 


—————— 


NOW IS THE TIME 

CID? DP. 6.=, "POR ALL” 
FOR ALL 

CID> GO 

AT: TESTB G1 689164 


CID> EXAMNIE @ 


|~ 


CID> S B 174 


ee 


SET TESTB G1 888174 
CID> GO 
AT: TESTB 01 GBG174 


1! 


8) 


9) 


18) 


11) 


12) 


13) 


14) 


152 


16) 


We attempt to continue execution at 
location 6 in segment @1 of TESTB. CID 
rejects the command; we can transfer 
control only to a point in the current 
environment (program and segment). 


Having set breakpoints for later in the 
session, we continue execution with the 
next statement. The program continues, 
displays a prompt, and waits for input. 


We enter the string "NOW IS THE TIME". 
The program continues execution until it 
reaches the breakpoint we set in Step 3. 


We EXAMINE the contents of INPUT-WORD to 
confirm that it matches the aetual 
entry. 


This command replaces the contents of 
INPUT-WORD with the string "FOR ALL". 
CID echoes the stored value. 


We continue execution. The program 
re-enters CID command mode when it 
reaches the breakpoint in TESTB that we 
set in Step 2. 


Now that TESTB has determined the length 


of the string, we examine the contents 
of SUB1 to see the character count. 
Note that the command is misspelled; 


CID looks only at the first character of 
the word. 


We set another breakpoint one statement 
later. 

Then we continue. CID regains control 
after the execution of a single COBOL 
statement. 

We examine the contents of 
CHARACTER-COUNT. Note that the 


"/LINKAGE" option is necessary because 
the data item is in the LINKAGE SECTION. 
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CID> S B 
BP: TESTB : @1 900164 
BP: TESTA : 91 OGOG46 


BP; TESTA : @2 888034 


BP: TESTB : @1 @@@174 
AT: TESTB : @1 @00174 


CID> CANCEL B 174 
CAN TESTB : 91 980174 


CID> GO 
LLA ROF 
AT: TESTA : 62 GOBG34 


~) 
Q 
Q 


E 


CID> GO 6 
LLA ROF 
AT: TESTA : G62 @G@G34 


CID> GO 
Al? TESTA. © O22 177777 


17) 


18) 


19) 


2G) 


21) 


22) 


We request a list of ail active 
breakpoints. CID also reports’ the 
current location. 


We cancel the breakpoint at location 
174. Note that the "B" is required, 
Since this is a two-word command. 


We continue execution. The program 
(TESTA) displays the result string that 
was returned by TESTB; it then enters 
CID command mode when it reaches the 
breakpoint we set in Step 4. 


We examine the contents of LETTER-COUNT. 
Note that a space is not required 
between a CID command and a numeric 
argument. 


We alter the flow of the program by 
specifying an offset in the GO command. 
CID transfers control to offset location 
6 in the current environment (segment @2 
of TESTA). The next COBOL statement 
executed is the DISPLAY at source line 
number 25; once again, CID regains 
control at the breakpoint set in step 4. 


We continue execution. When the program 
executes the STOP RUN’ statement, CID 


gains control and displays the 
pseudo-location 177777, which indicates 
program suspension (termination). Note 


that this is not an actual program 
location. 


We terminate the session (and the 
program, of course) by entering an XIT 
command. Since a STOP RUN has been 


executed, the program would also 
terminate if we entered a GO command 
with no location. We also could have 


continued program execution at another 
place by entering a GO command with a 
location. 
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DISPLAY 


STOP 


COBOL INTERACTIVE DEBUGGER (CID) 


Sample Program Listings 


GOOG 1 IDENTIFICATION .DIVISION. 
BOGG2 PROGRAM-ID. 
BEBG3 TESTA. 
GBGG4 DATE-WRITTEN. SEPTEMBER 1978. 
GGGG5 DATE-~COMPILED. 
GOOG6 13-SEP-78 . 
BOOOT ENVIRONMENT DIVISION. 
GESSS CONFIGURATION SECTION. 
BBGB9 SOURCE-COMPUTER. PDP-11. 
GOG19 OBJECT-COMPUTER. PDP-11. 
GOO11 DATA DIVISION. 
G0B12 WORKING-STORAGE SECTION. 
09013 @1 LETTER-COUNT PIC 9(2)V9(2). 
GOO14 G1 INPUT-WORD PIC X(2@). 
BGB15 G1 DISP-COUNT PIC 9(2). 
GOG16 PROCEDURE DIVISION. 
80017 GETIT SECTION. 
$0818 BEGINIT. 

: 81 SBBDGE 
60819 DISPLAY "ENTER WORD". 

> 81 BBBG24 
GO820 MOVE SPACES TO INPUT-WORD. 

> G1 GBGB34 
G0G21 ACCEPT INPUT-WORD. 

G1 BHOB4E 

BBB22 CALL "TESTB" USING INPUT-WORD LETTER-COUNT 
8B023 DISPLAYIT SECTION. 
BOG24 SHOW-IT. 

> @2 SHGGOE 
@BG25 DISPLAY INPUT-WORD. 

G2 BBGG24H 

68826 MOVE LETTER-COUNT TO DISP-COUNT. 


372 POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. 


G2 GOBG34 
G8G27 DISPLAY DISP-COUNT " CHARACTERS". 
G2 OB9G54 
GBG28 STOP RUN. 
DATA MAP 
NAME SOURCE DDIV DIR USAGE CLASS OCC LEN 
LINE LOCN LOC 
LETTER-COUNT 98813 @8G224 GAISBAS DISP NUM GB GOGH 
INPUT -WORD 99014 989239 BEGGS DISP AN GB BG2G 
DISP-COUNT 8015 @B0254 BGGG14 DISP NUM GB 8882 
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SBOSSE 
GBBG22 
GOOEH2 
BBOG52 


GOG164 


GBG174 


GBS2GH 


GEG3O4 


GGB322 


08334 


G8837G 


G20 1 
GGBG2 
GOGC3 
GAOO4 
GBOG5 
GOGGE 
OBOO7 
GOBHE 
GOOGI 
GOG1B 
60011 
GBGi12 
98013 
GGG14 
OBO15 
00016 
OOG17 
0018 
GGB19 
AEB2G 
GOG21 
OOG22 
GBG23 


GOB2H 
GBG25 
GGB26 
A2G27 
GBO28 
BBG29 
G8S3G 
$0031 
GOB32 
$8933 
GGB34 


98835 
GBO36 


98837 
00938 


68839 
GEBHD 


GOO41 
GEGH2 


IDENTIFICATION DIVISION. 
PROGRAM-ID.. 
TESTB. 
DATE-WRITTEN. SEPTEMBER 1978. 
DATE-COMPILED. 
13-SEP-78 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. PDP = 1.1% 
OBJECT-COMPUTER. PDP-11. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
G1 SUB1 PIC 9(2). 
G1 SUB2 PIC 9(2). 
G1 HOLD-WORD. 
@3 HOLD-CHAR PIC X OCCURS 2@ TIMES. 
LINKAGE SECTION. 
@1 THE-WORD. 
@3 THE-WORD-CHAR PIC X OCCURS 2@ TIMES. 
@1 CHARACTER-COUNT PIC 99V99. 
PROCEDURE DIVISION USING THE-WORD, CHARACTER-COUNT. 
CONVERT-IT SECTION. 
STARTUP. 


IF THE-WORD = SPACES 
MOVE @ TO CHARACTER-COUNT 
GO TO GET-OUT. 
PERFORM LOOK-BACK 
VARYING SUB1 FROM 2% BY -1 
UNTIL THE-WORD-CHAR (SUB1) NOT = SPACE. 
MOVE SUB1 TO CHARACTER-COUNT. 
MOVE SPACES TO HOLD-WORD. 
PERFORM MOVE-IT 
VARYING SUB2 FROM 1 BY 1 
UNTIL SUB1 = @. 


MOVE HOLD-WORD TO THE-WORD. 
GET-OUT. 


EXIT PROGRAM. 
MOVE-IT. 


MOVE THE-WORD-CHAR (SUB1) 
TO HOLD-CHAR (SUB2). 


SUBTRACT 1 FROM SUB1. 
LOOK-BACK. 


b3=I5 


EXIT 


LEVEL 


Lg 
L 
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01 GEB4GE 


NAME 


SUB1 

SUB2 

HOLD-WORD 
HOLD-CHAR 
THE-WORD 
THE-WORD-CHAR 
CHARACTER-COUNT 


EXIT « 


DATA MAP 
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SOURCE 
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80013 
GGO14 
88015 
GO016 
90018 
80819 
GOG2D 


DDIV 
LOCN 


GBF22H 
888226 
G00230 
GOG238 
GOCOGD 
GOOCBD 
GEGGGG 


DIR 
LOC 


BOSCO 
GOOOA6 
GOOG14 
G@BGG22 
OOTY) 
CGGGBE 
GB8G26 


USAGE CLASS OCC 


DISP 
DISP 
DISP 
DISP 
DISP 
DISP 
DISP 


NUM 
NUM 
AN 
AN 
AN 
AN 
NUM 


0G 
GO 
GB 
G1 
0O 
G1 
BO 


L] 


Gt 
Gt 
Gt 
Gt 
B\ 
Bi 
vy 


CHAPTER 14 


OPTIMIZATION 


Optimization is the process of designing or altering a program to 
minimize space allocation or execution time, or to achieve an 
effective trade-off between the two. 


This chapter provides guidelines for optimizing performance of COBOL 
programs. It is oriented toward optimization techniques that are 
controllable at the COBOL source language level. 


For more information on optimization techniques you can use _ through 
Record Management Services (RMS) facilities, refer to appropriate RMS 
documentation. 


Before attempting to optimize a program, you should know the space and 
time constraints imposed by your equipment. Estimate how often the 
program will be run, and its importance in the system. Some other 
points to consider are: 


l. What other routines are dependent on the results of your 


routine? 

2. What system resources are currently available? Will 
additional resources be added to your system in the near 
future? 


3. If program run times seem excessive, is the problem 
attributable to slow I/O, and is slow I/O due to a scarcity 
of disk space? 


14.1 OPTIMIZING MASS STORAGE I/0 


The COBOL source language is oriented toward commercial data 
processing applications, which tend to be heavily involved with file 
activity. Therefore, you can either enhance or undermine system 
performance, depending on how you design, populate, and handle files. 
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When writing or revising COBOL programs with optimization in mind, 
your fundamental goal should be to minimize I/O activity. Your 
answers to the following questions should influence your choice of 
file organization, record type, buffer size and number, and your 
program organization: 


1. What kinds of I/O operations are necessary to process’ the 


data? 
2. How can you best place I/O operations in the program? 


3. How should you structure the file? Are multiple access’ keys 
necessary or desirable? 


4. For each file, are frequent record updates and insertions 
likely, Or will file contents remain relatively (or 
absolutely) stable? 


5. How much task address space is available? 


14.2 PROGRAM DEVELOPMENT 


You can influence performance greatly by the way you organize your 
program. This section offers several guidelines toward an efficient 
program structure. 


14.2.1 Overlay Structure 


Reading overlays into memory requires considerable I/O activity. 
Therefore, you should plan overlay structure before writing the 
program. 


It is difficult to give specific suggestions that apply in all cases. 
However, if you cluster all file openings at the beginning of the 
program, and all file closings at the end, you can obviously place all 
record operations {READ, WRITE, REWRITE) between these portions. 
Then, by overriding the default RMS overlay structure, you can in some 
cases reduce the number of RMS-induced overlays during program 
execution. 


When you use a default RMS overlay structure, every RMS~ record 
Operation requires at least one overlay, and frequently more. By 
minimizing overlays, you can reduce task-build time as well as program 
run time. 


Be alert for situations in which read-write thrashing can occur, and 
try to coordinate I/O activity to eliminate them. You can avoid the 
I/O overhead penalty of an overlayed task structure by task-building 
without an ODL file and creating a non-overlayed task, although this 
is feasible only in rare cases. In any case, organize your program to 
obtain the maximum benefit from each overlay. 


The Task Builder Reference Manual describes ODL files in detail. 
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14.2.2 Sequentially Reading Indexed Fiies 


If you access an indexed file sequentially, and the file is 
write-shared, performance improves if you use OPEN I-O instead of OPEN 
INPUT. Using OPEN I-O implies a possibility that you will write to 
the file--even though you have no intention of doing so. 


Reading from a file that is open for input-output improves performance 
by locking the bucket, allowing you to obtain subsequent records from 
the same bucket without rereading it. 


14.2.3 Caching Index Roots 


RMS requires at least two buffers to process an indexed file. Each 
buffer is large enough to contain a single bucket. If your COBOL 
program does not contain a RESERVE n AREAS ciause, the compiler 
includes these two required buffers in your task by default. By 
including a RESERVE n AREAS in the SELECT statement for a file, you 
can cause additional (but not fewer) buffers for the processing of an 
indexed file. At run time, RMS will retain (cache) the roots of one 
or more indexes of the file in memory. The random access of any 


record through that index will then require one less I/O operation. 
The following rules apply for caching index roots: 
1. The file must not be shared at run time. 


2. Allocate one buffer for each key that your program uses to 
access file records, in addition to the two required buffers. 
For example, if the file contains a primary key and _ two 
alternate keys, and you use all of these keys to access 
records, you should allocate five buffers total. If you use 
only one key to access this file in a program, you need only 
one additional buffer area, or three in all. 


3. Use the RESERVE n AREAS clause to obtain this allocation, 
where n iS two more than the number of distinct keys used for 
access. For example, the clause RESERVE 5 AREAS’ causes 
allocation of the two required buffers, plus three buffer 
areas for caching the roots of three distinct file access 
keys. 


14.2.4 Multi-block Reading and Writing 


The multi-block read and write facility applies only to sequential 
files on disk devices. It allows reading or writing of more than one 
512-byte block at a time during a single I/O operation, reducing the 
number of I/O operations needed to process a file. However, the 
Single buffer used to process the file must be correspondingly longer. 
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To use this facility, be sure the file has SEQUENTIAL organization and 
resides on disk. Then, in the FD entry for the file, specify: 


BLOCK CONTAINS n CHARACTERS 


where n is a multiple of 512. Each such multiple represents’ the 
number of virtual blocks to be read or written during each access of 
the file. If n is not a multiple of 512, the compiler rounds the size 
to the next multiple of 512. 


14.3 FILE DESIGN 


This section describes the effect of file design on performance. The 
following suggestions apply to any type of file organization. 


1. Preallocate the entire file, contiguously if possible, using 
the /CO:n or /AL:n file switch (described in Table 14-1) or 
the RMS DEFINE utility. 


2. Select a suitable default extend quantity when you create the 
file, using the /EX:n file switch or the RMS DEFINE utility. 
(Refer to RMS documentation for a description of default 
extend quantities and the RMS DEFINE utility.) 


3. Know the relationships between record size and file storage, 
and try to define a record size suited for efficient storage 
and retrieval. 


4. Use the SAME RECORD AREA clause to save compute time and 
conserve address space. If records are being copied from one 
file to another, and both files share the same record area, 
no MOVE statement is needed to move record images between two 
record areas. The disadvantage is that records from both 
files cannot be available simultaneously unless one is moved 
to a work area. Note the distinction between the SAME RECORD 
AREA and SAME AREA clauses. 


5. The SAME AREA clause savesS even more address space than the 
SAME RECORD AREA clause by causing two or more files to share 
the same buffer area. However, not more than one of the 
files can be open at any one time. 


14.3.1 Sequential Files 


Sequential files have the simplest structure and the fewest options 
for definition, population, and handiing. Reduce the number of disk 
accesses by keeping record length to a minimum. With a sequential 
disk file, you can use the multi-block read and write facility 
described previously (that is, using the BLOCK CONTAINS n CHARACTERS 
clause in combination with ORGANIZATION IS SEQUENTIAL). Aliso, you can 
reduce overlay activity by grouping all sequential file record 
Operations into one overlay. 
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14.3.2 Relative Files 
For relative files: 


1. Select a record format and size that minimizes the empty 
Space remaining in each record position and each bucket. 


2. If you create the file by means of the RMS DEFINE utility, 
select a realistic maximum record number. An attempt to 
insert a record with a number higher than the maximum will 
fail. Before inserting such a record, a redefinition and 
repopulation of the file is required. 


3. Group relative file operations into one overlay. This 
reduces task-build time and run time. 


4, Be aware that, before writing a record into a relative file, 
all buckets up to and including the bucket into which the 
record insertion will occur must be formatted. Thus, write 
operations have variable response times, depending on whether 
preliminary formatting is required, and how much. You might 
consider writing the highest-numhered record first to force 


formatting of the entire file only once. 


14.3.3 Indexed Files 


Indexed files have by far the greatest potential for inefficient 
usage. When using this file organization, be especially attentive to 
the issue of how well the design and use of the files map into the 
application. 


To use indexed files efficiently, you must first understand how they 
are organized and processed. As the name suggests, an indexed file 
contains not only a set of data records, but also information to 
facilitate access to the records. 


A bucket is an integral number of contiguous 512-byte virtual blocks, 
and the number of virtual blocks is known as the bucket size. The 
bucket is the basic retrievable element of an indexed file. 


Every indexed file must have a primary key: a field in the record 
that contains a unique value for each individual record. When RMS 
writes records into the indexed file, it arranges them in collated 
sequence, according to increasing primary key value, in a series of 
chained buckets. 


Thus, you can access the records sequentially by specifying ACCESS 
SEQUENTIAL. In fact, one advantage of the indexed file is that you 
can access it either sequentially or randomly. 


As RMS writes the records, it also constructs and maintains a 
tree-like structure of key-value and location pointers. Figure 14-1 
shows conceptually the overall structure of a primary key index. Each 
element of the index structure is a bucket. The buckets of the index 
are structured into a hierarchy of levels. The highest level of the 
index consists of a single bucket, called the root bucket. The root 
bucket contains location pointers to buckets at the next lower level. 
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Thus RMS scans one bucket at each level of the index for a pointer to 
a bucket at the next level, until it reaches the bottom level of the 
index; the bottom level is called the data level. Ina primary key 
index, this level contains the actual data records of the indexed 
file. The buckets in each level above the data level are called index 
buckets. 


RMS also constructs an index for each alternate key that you define 
for the file. Like the primary index, alternate key indexes are 
contained in the file. However, alternate key indexes do not contain 
actual data records at the data level; instead, they contain pointers 
to data records in the data level of the primary index. 


For discussion purposes, the successive levels of an index are 
numbered. The data level of the index is level zero, and the number 
of levels above level zero is considered the depth of the index. Thus 
the level number of the root bucket is equal to the depth of the 
index. 


Each random’ access request begins by comparing specific key value 
against the entries in the root bucket, seeking the first entry in the 
root bucket whose key value is equal to or greater than the access 
request key. (This search is always successful, because the root 
bucket‘s highest key vaiue is the highest possibie vaiue that the key 
field can contain.) Having located the proper key value, RMS takes the 
bucket pointer associated with that vaiue and uses it to bring the 
target bucket on the next lower level into memory. This process is 
repeated for each level of the index. RMS thus searches one bucket at 
each’ level of the index until it reaches a target bucket at the data 
level. At this point the desired data record location is determined, 
and a data record can be retrieved or deleted, if present, or written 
if such writing will not produce a duplicate primary key value. 


At times there may be insufficient room in a data level bucket to 
accommodate a new record. When this occurs, RMS includes a new bucket 
in the chain, moving enough records from the old bucket to preserve 
the key value sequence while making room to write the new record. 
This action is known as a bucket split. 


In summary, each index of an indexed file provides the mechanism for 
random access to records. Sequential access to records is also 
possible, because the records themselves (in the primary index) or 
pointers to the records (in each alternate index) are collated in 
ascending key value order throughout a series of linked buckets. 


14.3.3.1 General Rules for Indexed Files - You can apply the 
following general rules for indexed files by direct alteration of 
COBOL source code. 








1. While alternate keys are often useful, the more keys you 
define for an indexed file, the longer each WRITE , REWRITE, 
Or DELETE operation takes. However, multiple keys have 
little effect on READ timing and provide multiple access 
paths. Thus, they are most useful for files that are not 
subject to frequent additions and updates and are accessed in 
many different programs. 


14-7 


OPTIMIZATION 


2. Select bucket sizes that reflect file activity and provide a 
Suitable depth of index structure. (See Section 14.3.3.3, 
Index Depth.) 


3. Avoid excessive duplication of key values. COBOL does not 
allow duplicates on the primary key, but permits them on 
alternate keys. 


The following subsections deal with the specifics of indexed file 
design and creation. 


14.3.3.2 Bucket Size - Bucket size selection can influence indexed 
file performance markedly. 





To RMS, bucket size is expressed aS an integral number of virtual 
blocks, each 512 bytes long. Thus, a bucket size of 1 specifies a 
512-byte bucket, while a bucket size of 2 ‘specifies a 1f24-byte 
bucket, and so on. 


However, in COBOL you do not express bucket size in exactly those 
terms. The compiler passes bucket size values to RMS based on what 
you specify in the BLOCK CONTAINS clause. There, you indicate bucket 
Size in terms of records or characters. 


If you express BLOCK SIZE in records, the bucket can in some cases 
contain more records than you specify, but never fewer. For example, 
assume that your file contains fixed-size 1ff-byte records, and you 
call for each bucket to contain five records, as follows: 


BLOCK CONTAINS 5 RECORDS 


This might seem to define a bucket as a 512-byte block containing five 
records of 1f@ bytes each. However, the compiler adds RMS record and 
bucket overhead to each bucket for control purposes, as follows: 


Bucket Overhead 15 bytes per bucket 


Record Overhead 7 bytes per record (fixed-length) 
9 bytes per record (variable-length) 


Thus, in the example, bucket size is calculated as follows: 


Bucket Overhead 15 bytes 
Record Size is 19% bytes 
+ 7 bytes Record Overhead 
for each of 5 records 





Total Record Space is ({1#M + 7)*5, or 535 bytes 
Total Block specified by user 55@ bytes 


Because virtual blocks are 512 bytes long and buckets are always some 
integral number of virtual blocks, the smallest buffer that the 
compiler can specify in this case 1s two virtual blocks (1924 bytes), 
not one. RMS, however, is not keyed to the BLOCK CONTAINS clause from 
which this bucket specification was derived, and puts as many records 
as will fit into each bucket. The bucket actually will contain nine 
records, not five. 
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This effect may be desirable or undesirable, and no judgement is 
intended here. Nevertheless, as a COBOL user concerned with file 
optimization, you should be aware of the mechanism by which COBOL 
record and file descriptions are used to derive bucket sizes. 


The CHARACTERS option of the BLOCK CONTAINS clause allows you _ to 
specify bucket size more directly. For example: 


BLOCK CONTAINS 2848 CHARACTERS 


This calls for a bucket size of four 512-byte virtual blocks. The 
number of characters in a bucket is always a multiple of 512. 


14.3.3.3 Index Depth - The size of data records, key fields, and 
buckets in the file determines the depth of the index. Index depth, 
in turn, determines the number of disk accesses required to retrieve a 
particular record. 








In general, performance is best with an index depth of 3 or 4. A 
shallower index will require fewer accesses, but will reduce available 
address space because of the larger buffers required. 


14.3.3.4 File Activity - After the initial population of an indexed 
file, much of its activity is limited to record retrieval. In 
selecting a bucket size, also consider the likely frequency of random 
insert and delete operations. 





When a record is inserted, there must be sufficient room in the bucket 
to contain it. Otherwise, a bucket split occurs. Bucket splits can 
cause accumulation of storage overhead, and a consequent reduction of 
usable space. The new bucket contains records moved from the original 
bucket to make room for the new record. For each record moved out of 
the original bucket, seven bytes remain. Therefore, a bucket could 
accumulate overhead from bucket splits, possibly reducing usable space 
so much that it can no longer receive record insertions. 


Record deletions also can accumulate storage overhead. Under most 
circumstances, however, most of the space that was occupied by the 
Original record becomes available for reuse. When duplicate primary 
keys are not allowed (as is always true with COBOL file operations), 
RMS can reclaim all but two bytes of the deleted record space. 


Several ways of avoiding overhead accumulation are available. First, 
determine or estimate the frequency with which certain operations will 
occur. If, for example, you expect only 19M records of a 19,08 
record file to be added or deleted in an average month, your data base 
is stable enough that you might decide to allow some wasted space from 
record additions and deletions. 
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However, if you expect more frequent additions and deletions, try the 
following: 


1. Choose a bucket size that allows for overhead accumulation, 
if possible. Avoid bucket sizes that are an exact or near 
multiple of your record size. 


2. To optimize for record insertion performance (as opposed to 
Space optimization), first define the file with a fill number 
{using the RMS DEFINE utility or a MACRO program). A fill 
number specifies the number of bytes in the buckets of the 
file that you want to contain record information when the 
file is populated. Then, populate the file specifying the 
/LO switch (see Table 14-1 or RMS utilities documentation). 
Thereafter, the unused space iS available for _ record 
insertions, with minimum bucket splitting. Make certain that 
programs that perform such record insertions do not specify 
the /LO switch. 


14.4 OPTIMIZING COMPUTATION 


You can improve computational efficiency by choosing data types 
carefully and avoiding coding techniques that produce inefficient 
object code. For example: 


1. Choose USAGE COMPUTATIONAL to maximize efficiency in 
arithmetic operations. Other data types, in decreasing order 
of efficiency, are: DISPLAY, COMPUTATIONAL-6, and 
COMPUTATIONAL-3. 


2. Avoid arithmetic operations that use more than one data type. 


3. When uSing COMPUTATIONAL data, minimize the size of the data 
items; this data type becomes exponentially less efficient 
as the size of elementary data items increases. 


4. Define subscripts as COMPUTATIONAL whenever possible. 


5. Indexing is slightly less efficient than subscripting with 
single-word COMPUTATIONAL data items, but significantly more 
efficient than using subscripts of any other type. 


6. If you can ensure that subscripts are always valid, you can 
use the switch, /-BOU, to suppress boundary checking. 
However, you risk unpredictable results if a subscript or 
index contains an out-of-range value. 


7. Avoid COMPUTE statements and expressions with many factors 
and operators to improve execution time. 


8. Avoid COMPUTATIONAL-6 to increase efficiency and 
compatibility. 
NOTE 
COMPUTATIONAL-6 iS a temporary data format intended 
only for program conversion from releases of PDP-1l 


COBOL prior to Version 4.@. 
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14.5 FILE SPECIFICATION SWITCHES 


In PDP-11 COBOL, you can identify a file by its file specification in 
either the Environment Division SELECT statement (using the ASSIGN 
clause) or the VALUE OF ID clause in the Data Division 
file-description-entry. These are the only places in a COBOL program 
where you can refer to a file in terms of its system-specific 
identification. 


When you specify a file, you can qualify it with various switches, 
which are described in Table 14-1. These switches influence the 
storage and handling of files and are an aid in applying some of the 
optimization techniques described earlier in this chapter. 


Table 14-1 
FILE SPECIFICATION SWITCHES 


a cea a a AAR 


SWITCH MEANING 
/AL:n Allocate n disk blocks to the file when it is created. 


| | This ensures that n blocks aré available before 
| processing begins. The switch can also be used to 
ensure that the volume can hoid the entire file. if the 
output medium is an RK-type disk, the maximum value of n 
is 49@@ (decimal). If n includes a decimal point as its 
| rightmost character, it is considered decimal; if it 
| 

| | 





includes no decimal point, it is considered octal. 
The biocks allocated need not be contiguous. 
NOTE 
The /AL switch is not Supported by RSTS/E. 
Allocate disk space in clusters of n_ blocks. This 
Switch applies only to RSTS/E. 
Specify nas a power of 2 in the range 1 to 256 


(decimal), or 1 to 4f@ (octal). If n has no decimal 
point, it is considered octal. 


This switch is used only when creating very large files 
on an output device that can hold the entire file (such 
as an RP#3 disk). It speeds file access when tthe file 
is being processed sequentially. 
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/CO:n 


/EX:n 


/LO 
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Table 14-1 (continued) 
FILE SPECIFICATION SWITCHES 


This switch is similar to /AL:n, except that it further 
specifies that all blocks be contiguous. 


Specifies at file creation time an extension quantity of 
n blocks. A reasonably large extension quantity 
minimizes the overhead of dynamic extend operations. 


Instructs RMS to observe the fill numbers specified at 
file creation time. If you specify /LO, the buckets of 
the file will contain free space to allow later record 
insertions. | 


Specifies sharing of the file for output or I/O mode, 
making it available for writing or altering by other 
tasks running concurrently with the COBOL program. This 
switch is not allowed for sequential files. For other 
types of files, the following rules apply. 





1. If the /SH is specified for one task _ sharing 
the file, it must be specified for all tasks 
sharing the file. 


2. If a file is being opened for OUTPUT or I/O 
with the /SH switch specified, all other tasks 
currently using the file must also have the /SH 
switch specified. 


3. If a file is opened for input without the /SH 
Switch set, no other task can use the file for 
output or I/O. 


4. If a file is opened for input without the /SH 
Switch set, no other task currently using the 
file can have the /SH switch set. 


If access is denied because one of the above’ rules has 
been violated, a file status code of 91 is stored in the 
FILE-STATUS data-item associated with the file, assuming 
that the SELECT statement for the file contains a 
FILE-STATUS clause. 


(RSX-11M systems only) Allows you to set the number of 


retrieval pointers in the window used to map virtual 
block numbers to logical block numbers. The acceptable 
values are 1 to 182 if you know exactly how many 
pointers are present on disk for the file, or 255, which 
requests assignment of pointers as needed. If /WI:n is 





| | not present, the default is 7. | 


APPENDIX A 


THE COBOL FORMAT 


COBOL NOTATION USED IN FORMATS 


= 
w 


NOTE: 


Underlined upper-case words (key words) - required words; 
Maan taArAaa lnn 
VEPPpet” Sasce WUELUudoS (ilu 


Lower-case words - generic terms, must be supplied by the user; 


Brackets [] - enclosed portion is optional; if several enclosed words are 
vertically stacked, only one of them may be used; 


Braces {} - a selection must be made from the vertical stack of enclosed words; 
Ellipsis ..-. = the position at which repetition may occur; 

Comma and semicolon - optional punctuation; 

Period - eeqaeedneee shown in the formats. 


Shaded items represent PDP=-11 COBOL extensions to the ANS-74 list of 
COBOL formats. 


IDENTIFICATION DIVISION. 


PROGRAM-ID. program-name. 


[AUTHOR. 


[comment-entry]...] 


[INSTALLATION. [comment-entry]...] 
(DATE-WRITTEN. [comment~entry]...] 
[DATE=COMPTLED. [comment-entry]...] 
(SECURITY. [comment~entry]...] 


ENVIRONMENT DIVISION, 


CONFIGURATION SECTION. 





SOURCE-COMPUTER. PDP-11. 
WORDS 
OBJECT=COMPUTER. PDP=-11 MEMORY SIZE integer CHARACTERS 
MODULES 


[PROGRAM COLLATING SEQUENCE IS alphabet-name] 
[SEGMENT-LIMIT IS segment-number]. 


A=1 


THE COBOL FORMAT 


[SPECIAL=NAMES. 
[CARD-READER is mnemonic=name-1] 
[CONSOLE is mnemonic=-name-2] 
[LINE-PRINTER IS mnemonic-name-3] 
{[PAPER-TAPE-PUNCH IS mnemonic-name-4] 
[PAPER-TAPE-READER IS mnemonic-name-5] 
SWITCH integer-1 ON STATUS IS condition-name-1 

OFF STATUS IS condition-name-2 


NATIVE 
[ Atpnabet-nane Is | ae 1 | 


[CURRENCY SIGN Is literal-1] 
[DECIMAL-POINT IS COMMA ].] 


{INPUT-OUTPUT SECTION. 


FILE-CONTROL. {file-control-entry}... 


Format 1: 
SELECT [OPTIONAL] file-name 


ASSIGN TO literal-1 


: AREA 
[ RESERVE integer-1 [ all 


[: ORGANIZATION IS SEQUENTIAL] 

[; ACCESS MODE IS SEQUENTIAL] 

[; FILE STATUS IS data-name-1] . 
Format 2: 


SELECT file-name 


ASSIGN TO literal-1 
F AREA 
[ RESERVE integer=-1 baal 


7 ORGANIZATION IS RELATIVE 


’ 


[OFF STATUS is condition-name~2] 
[ON STATUS IS condition-name-1] 


SEQUENTIAL {, RELATIVE KEY IS data-name-1] 


; ACCESS MODE IS RANDOM 
STE | RELATIVE KEY IS data-name-1 


; FILE STATUS IS data-name-2] . 


Format 3: 
SELECT file-name 


ASSIGN TO literal-1 


‘ AREA 
[ RESERVE integer=-1 | 


+ ORGANIZATION IS INDEXED 


I] - 


THE COBOL FORMAT 


= 


SEQUENTIAL 
; ACCESS MODE IS RANDOM 
DYNAMIC 


RECORD KEY IS data-name-1 
ALTERNATE RECORD KEY IS data=name-2 [WITH DUPLICATES]]... 
FILE STATUS IS data-name-3] . 


~e Me ON 


[ 

[ 

[I-O-CONTROL. 

[SAME [RECORD] AREA FOR file-name-1 {file-name-2}...]... 

[MULTIPLE FILE TAPE CONTAINS file-name=3 [POSITION integer-1] 
[file-name-4 [POSITION integéer=2] 2.6] ss 


[ APPLY PRINT-CONTROL ON file-name-5 [file-name-6]... ] avaell 


DATA DIVISION. 


(FILE SECTION. 
[FD file-name 


T f mam nnn v1 
‘ . RECURUS 
K - = —— 
[Buoc CONTAINS [integer-1 TO] integer-2 | GHaracters| | 
[RECORD CONTAINS [integer=-3 TO) integer-4 CHARACTERS ]} 
RECORD Is } STANDARD 
a [Se ARE (ae 
data-name-1 
[wane oF 20 25 [Steal |} 
RECORD IS 
T. Fee ety — = = = eee eco 
[para A { RECORD ace data-name=3 [data-name-4] 
a { data-name-5} data-name-6) | 
LINAGE IS iE j LINES WITH FOOTING AT 
— integer-5 —_—— integer-6 


etre anne eee 


integer-7 
[CODE-SET IS alphabet-name]. 
{record-description-entry]...]...] 
(WORKING-STORAGE SECTION. 
Piseoie ere eee 
record-description-entry 


] [osama | 


data-name-8 
integer-8 


wie] 


THE COBOL FORMAT 


{LINKAGE SECTION, 
(eee 

record-description-entry ae | 
Data description entry: 
Format 1: 

ao «| 
FILLER 
[REDEFINES data-name-~2] 

sees | 


level-number | 
[fe 
L|PIc 
COMPUTATIONAL 
COMP 
COMPUTATIONAL-6 
OMP- 
(USAGE IS] § COMPUTATIONAL~3 
COMP— 
| DISPLAY 
DISPLAY=6 
DISPLAY=7 
INDEX 
LEADING 
reuGN 2) | Serene 


—— LEFT 
RIGHT 





[SEPARATE CHARACTER] 





SUSEIEIED 
RIGHT 
aan WHEN ZERO] 
[VALUE Is literal] 
integer-1 TO integer-2 TIMES DEPENDING ON data-name-3 
OCCURS . —— —— 
integer-2 TIMES 


ASCENDING 
| DESCENDING KEY IS data-name-4 [data-name-5]... ] aee 
[INDEXED BY index-name-1 {index-name~2] 1] e 
Format 2: 
66 data-name-l1 RENAMES data-name-2 
THROUGH 
THRU data-name-3 |, 


Format 3: ~~ 








dae { VALUE TS C{ rHROuGH } 7 
88 = ; os Seatac tiedadi kas : = 
condition=name | VALUES ARE literal-1 | | THRU j literal al 
THROUGH : 
[2seeraa 3 [| sane Laoa See. eke 


PROCEDURE DIVISION [USING [data-name-1][,data-name-2] ...]. 
Format 1: 


[DECLARATIVES. 

{section-name SECTION [segment-number] . declarative-sentence 
[paragraph-name. [sentence]...]...}ee- 

END DECLARATIVES.] 

Tsection-name SECTION [segment-number]. 

[paragraph-name. [sentence]...Jeeeleee 


{paragraph-name. [sentence]...}... 


THE COBOL FORMAT 


STATEMENTS 


ACCEPT identifier [FROM mnemonic=name] 


DATE 
ACCEPT identifier FROM DAY 
TIME 
app fidentéfier-1} [isentifier-2] no identifier-m [ROUNDED] 
[identifier-n [ROUNDED]]...[ON SIZE ERROR imperative-statement] 
aera, identifier-2 re eee 
= fe literal-2 | eee one 


GIVING identifier-m [ROUNDED] f[identifier-n [ROUNDED]] ... 
[ON SIZE ERROR imperative~statement] 


ADD 


CORRESPONDING 
CORR identifier-1 TO identifier-2 [ROUNDED] 
[ON SIZE ERROR imperative=statement] 


ALTER procedure=name=-1 TO [PROCEED TO] procedure-name-2 
3 


[procedure-name- O [PROCEED TO] procedure-name-4]..«- 


CALL literal-1l 
[USING data-name-1 [,data-name-2]...] 








im . : bs 
{=| pes NO SN | fad bay NO | 
F REM 
— wrta | NQ REWIND ona NO REWIND 
LOCK LOCK 


COMPUTE identifier-1 [ROUNDED] [identifier-2 [ROUNDED]] ... 
= arithmetic-expression [ON SIZE ERROR imperative-statement] 


DELETE file-name RECORD {INVALID KEY imperative-statement] 
identifier-1 identifier~2 
ene eae pee | a 


[UPON mnemonic-name] [WITH NO ADVANCING] 








pivipg | identifier-1 INTO identifier-2 [ROUNDED] 

_—_——— literal-1 — _—_ 
[identifier-3[ROUNDED]] ... [ON SIZE ERROR imperative-statement] 
identifier-1 identifier-2 ; ae 

DIVIDE eee INTO eee GIVING identifier-3 [ROUNDED] 
[identifier-4[ROUNDED]]...[ON SIZE ERROR imperative-statement] 
identifier-1 identifier-2 ‘ ets 

DIVIDE een | BY freee: | GIVING identifier-3 [ROUNDED] 
{identifier-4[ROUNDED]]...[ON SIZE ERROR imperative-statement] 
identifier-1 identifier-2 ; aoe 

DIVIDE ee | INTO {rei sieaaries GIVING identifier-3 [ROUNDED] 
REMAINDER identifier-4[ON SIZE ERROR imperative-statement] 
i tifier- i ifier-2 ; wes 

prvipe =| +dentifier-1 BY paeneErese GIVING identifier~3 [ROUNDED] 
literal-1 —_ literal-2 —— ————— 


REMAINDER identifier-4[ON SIZE ERROR imperative-statement] 


EXIT [PROGRAM] 


TO [procedure-name-1] 
TO procedure=name-1 [procedure~name-2]...procedure-name-n DEPENDING ON identifier 


Isls 


THE COBOL FORMAT 





IF condition 


statement-1 ELSE statement-2 
NEXT SENTENCE ELSE NEXT SENTENCE 


INSPECT identifier-1 TALLYING 








ALL identifier-3 ‘ sath 
identifier-2 FOR {Enc | eae. | =| INITIAL eee cat 
CHARACTERS ———— pee 
INSPECT identifier-1 REPLACING 
identifier-6 BEFORE identifier-7 
cuaracters py = |1fe0re | || Sse mirran {eer ales | 
ALL : poe ; rl 
LEADING ree BY rea BEFORE INITIAL ae oan . 
FIRST literal=-3 —_— literal-4 AFTER literal-5 


INSPECT identifier-1 TALLYING 


[ | eer 
identifier-2 FOR LEADING lit - BEFO i ifier- 
ier iteral-1 | =| arent ea ‘I | ; 





CHARACTERS AFTER literal-2 
REPLACING 
identifier-6 BEFORE identifier-7 
CHARACTERS BY 
Sa fee: | (a AFTER RNSEAE eae | 
ALL 
— identifier-5 identifier-6 BEFORE identifier-7 
LEADING ; : erate 
| ison rece | = retentey | | AFTER ai reseoer | 
FIRST 
identifier-1 F dak i oor 
MOVE : TO identifier-2 [identifier-3] ... 
— literal _ 


MOVE 


{ SoaeesPowpins RESPONDING | identifier-1 TO identifier-2 


CORR 


identifier-1l 


literal-1 | BY identifier-2 [ROUNDED] 


»*MULTIPLY 


[identifier-3 [ROUNDED]] ... [ON SIZE ERROR imperative-statement] 


SeGHELE Leos Hee | GIVING identifier-3 [ROUNDED] 


MULTIPLY oa EL literal-2 


{identifier-4 [ROUNDED]] ... [ON SIZE ERROR imperative-statement] 


INPUT file-name~1(WITH NO REWIND] [file-name-2 [WITH NO REWIND]]... 

OUTPUT file-name-3 [WITH NO REWIND] ([file-name-4 [WITH NO REWIND] ]... eee 
I-O file-name-5 [file-name-6]... 
| EXTEND file-name-7 [file-name-8]... 





OPEN 


procedure-name-2 


THROUGH 
PERFORM procedure-name-1 { eee uy 


THRU 


PERFORM procedure~name-1 | cee linteger-1 TIMES 


[| THROUGH 


procedure=name=2 
| | THRU si a 


PERFORM procedure=name=1 





[ THROUGH 
procedure-name-2 


[ THRU 


| Remooe | eames {identifier-1 
| ] 
| 
PERFORM procedure~name-1 senouss | | 


identifier-2 } 


identifier-3 
index-name-1 


FROM | ndexane 
iteral 


ae } 


VARYING | 


BY UNTIL condition-1 


identifier-4 
literal-2 


A-6 


THE COBOL FORMAT 


[ identifier-5 identifier-6 
AFTER | | FROM index-name-4 
—_— index-name-3 — : 

literal-3 
BY edi UNTIL condition-2 
—_— literal=-4 — 
identifier-9 
AFTER paces FROM index=-name-6 
index-name=5 —_— A 
literal-5 
BY oe UNTIL condition-3 
— literal-6 —_—_—— 


READ file-name [NEXT]RECORD[INTO identifier] [AT END imperative-statement] 

READ file-name RECORD[INTO identifier] [INVALID KEY imperative-statement] 

READ file-name RECORD[INTO identifier] [;KEY IS data-name] [;INVALID KEY imperative-statement] 
REWRITE record=name [FROM identifier] [INVALID KEY imperative-statement] 


r 
SEARCH identifier-1 esse 








le see 511 
identifier- i i 
| aie viata | | [AT END imperative-statement-1] 


index-name-1 


{ imperative-statement-2 | 
| NEXT SENTENCE J 





[ ae imperative-statement-3 
en condition=2 ae SENTENCE eis 


SEARCH ALL identifier-1[AT END imperative-statement~1] 





( data-name-1 len mane mnt {identifier-3 ) 
to BYVAL LU . 
\ gs = j literal-1 
W Bins i ic- 3] - 
VHEN Gonaaetonciame=a arithmetic-expression-1l 
identifier-4 
data-name~2 (ee —™| [icra 
AND arithmetic-expression-2 wee 
condition-name-2 
imperative-statement-2 
NEXT SENTENCE 
: aed identifier-3 
identifier-1l {identifier-2]... i 
SET ; A TO index-name-3 
— |index-name-1 [index-name-2]... _ 
integer-1 
SET index-name-4 [index-name-5]... ee “| ee 4 
<— DOWN BY integer-2 
IS EQUAL TO 
Is = 
TER THAN 
START file-name KEY = aa data~name 
IS NOT LESS THAN 
IS NOT < 


[INVALID KEY imperative-statement] 


—— | Sieerat| 


THE COBOL FORMAT 


identifier-1 identifier-2 identifier-3 
STRING gee fe ] eee DELIMITED BY literal-3 
SIZE 
identifier-4 identifier-5 identifier-6 


SIZE 





INTO identifier-7 [WITH POINTER identifier-8] 
[ON OVERFLOW imperative-statement] 
SUBTRACT | 


identifier-1 identifier-2 . ois 
ieeraiey | Epa ] aces FROM identifier-m[ROUNDED] 


[identifier-n [ROUNDED]]...[ON SIZE ERROR imperative-statement] 
SUBTRACT 


literal-1 literal-2 cee FROM 





fee | ear oy 


literal-m 


GIVING identifier-n [ROUNDED] [identifier-o[ROUNDED]]... 
{ON SIZE ERROR imperative-statement] 


CORRESPONDING 
SUBTRACT i= | 


[ON SIZE ERROR imperative-statement] 





identifier-1 FROM identifier-2 [ROUNDED] 


UNSTRING identifier-1 
identifier-2 identifier-3 ee6 
| penimaren ey tau) {fennel for ams [ee oo] 
INTO identifier-4 [DELIMITER IN identifier-5] [COUNT IN identifier-6] 
[identifier-7 [DELIMITER IN identifier-8] [COUNT IN identifier-9]]... 
(WITH POINTER identifier-10] [TALLYING IN identifier-11] 
[ON OVERFLOW imperative-statement] 


file-name~1 [file-name-2]... 


INPUT 
USE AFTER STANDARD EEN PROCEDURE ON OUTPUT 
— ERROR —— ——— 
SRROE I-0 
EXTEND 


WRITE record-name [FROM identifier-1] 


identifier-2 LINE 
BEFORE HF | i 
{ Bere ADVANCING integer LINES 
[PAGE] 
Ps {END-OF-PAGE}) . ae ao ane 
[AT | EOP j imperative-statementj 


WRITE record=-name [FROM identifier] [INVALID KEY imperative-statement] 





hey heat 
ia literal-3 ] 
Oot ar { literal-1] . { literal-2] 
——- | word=1 Be | word=2 Jj vd 


NOTE: A COPY statement may appear anywhere that a word appears in the COBOL source program. 


LUN 


10 
li 
12 
13 
14 


APPENDIX B 


LOGICAL UNIT NUMBER (LUN) ASSIGNMENTS 


ASSIGNMENT 
Console, input 
Console, output 
Source input file 
Source listing output file 
Object output file 
ODL output file 
CREF scratch file 
COPY library input file 
Work file 
Work file 
Intermediate file 
Sort work file 
Sort work file 


Sort work file 


APPENDIX C 


PDP-11 COBOL COMPILER IMPLEMENTATION LIMITATIONS 


This appendix describes the implementation limitations for the PDP-1l 
COBOL compiler system (compiler and OTS). You should not confuse the 
term "limitation" with "restriction". A restriction is a language 
facility that is not implemented or should not be used due to known 
errors in its implementation. An implementation limitation quantifies 
the limits of a language facility that is supported by the system. 


Practical implementation limitations exist in every compiler; They 
result from the finite size of compiler tables, compiler data 
structure representations, and so on. Since the PDP-11 COBOL compiler 
employs a WVirtuai Memory System to support many compiler data 
structures, the quantities specified for some implementation 
limitations are approximations. However, aS a general ruie, the 
following guidelines should not be exceeded in the development of a 
COBOL program. 


IMPLEMENTATION LIMITATIONS 
1. The default depth of dynamic PERFORM statement nesting is 19. 
The default depth can be modified by using the /PFM switch at 


compile time. 


2. The maximum number of sending operands in a DISPLAY statement 
is 16. 


3. The maximum number of data-name definitions in a COBOL 
program is approximately 2999. 


4. The maximum number of procedure name definitions in a COBOL 
program is approximately 2999. 


5. The maximum nesting depth of matching parentheses in a COBOL 
expression is 1@. 


6. The maximum number of qualifiers in a qualified data-name 
reference is 48. 


7. The maximum number of procedure names in a GO TO DEPENDING 
Statement is 16. 


APPENDIX D 


COMPILER GENERATED PSECTS 


An object program generated by the PDP-1l1 COBOL compiler is composed 
of program sections called PSECTs. Three types of PSECTs are 
generated: 


@e Data Psects Contain the memory for the Data Division 
of a COBOL program. 


e Control PSECTS Contain the data that is required by the 
OTS during program execution. 
@e Procedural PSECTS Contain the object code generated for 


the Procedure Division. 


Data and Control PSECTs are always non-overlayable. Procedural 
PSECTsS, however, can be optionally overlayable or non-overlayable. 


D.1 PSECT NAMING CONVENTIONS 


The PSECTsS generated by the PDP-11 COBOL compiler are named entities. 
Each PSECT name is composed of a three character prefix followed by a 
three character suffix. There are two different forms of the prefix: 


@ SKK 
Where: $ Is a sentinel character and is always present. 


KK Is a two character kernel that identifies the 
PSECT. It is this kernel character that is 
specified by the /KER:kk switch. The /KER:kk 
switch is appended to the compiler command line to 
assign a unique kernel value to the PSECTsS 
generated during the compilation. The default 
kernel assignment is CS. 


e SCB 
Where: $ Is a sentinel character, and is always present. 


CB Is a two character code that identifies the PSECT 
as a COBOL compiler generated PSECT. 


COMPILER GENERATED PSECTS 


PSECTS with the prefix S$CB are generated to provide the 
control and work space required for I/O operations. 


PSECTS with these same names are generated for each COBOL 
compilation. They are either overlayed or concatenated at 
task-build time. Those that are overlayed, have a known fixed 
length at task-build time. Those that are concatenated, have 
a known length at compile-time and contribute their size to 
the total size of the PSECT that is built by the Task Builder. 


The three character suffix identifies the type of code or data _ the 
PSECT contains. Table D-1l describes the suffixes assigned to SKK type 
PSECTs, and Table D-2 describes the suffixes assigned to $CB_ type 
PSECTS. 


Table D-1l 
SKK PSECT Name Suffixes 







Content 


Sattix 








Data Division data storage areas. 














Data Division directories = contains 
descriptions of referenced Data Division 
items. 











Directories of referenced Linkage Section 
items. 










Literal Pool - contains all of the literals 
referenced in the program. 


Literal Directory. 






Input/Output buffers. 





Control COBOL compile unit work space - contains a 





destination of alterable GO TO statements. 


| 
| description of the compile unit 
| | environment, 
| | PDT PSECT dispatch table = used for 
intra-program control of segmented COBOL | 
| programs. 
{ 
| 
| SDT Subprogram dispatch table - used for 
| inter-program control (i.e., calling 
| subprograms). 
! | | 
| | LST Argument list work space - used to contain | 
| ; the argument ilist passed to the calied 
| | | subprogram. | 
| | | | 
| | PFM | Perform work space - used to provide | 
| control and checking of nested PERFORM | 
| | | statements. 
| 
| | ADT | ALTER Dispatch Table - used to contain the | 
| H | { 
| | | | 


COMPILER GENERATED PSECTS 


Table D-1 (Cont.) 
SKK PSECT Name Suffixes 






Content 










Default USE procedure table - used to 
access the default OPEN mode (INPUT, 
OUTPUT, I-O, or EXTEND) USE procedures, if 
present. 










ENT Code generated by the compiler for _ the 
program entry point. 


Procedural 













nnn | Numbered suffixes beginning with OOl. | 
These numbered PSECTsS contain the object 
code generated for the Procedure Division | 
of a COBOL program. 












Tabie D-z 
PSECT Name Suffixes 


(ee ee ee el 


Allocation Suffix Content 


Input/Output Table - contains a reference 
to each COBOL Input/Output OTS routine 
| required by the COBOL compilation. 















information to RMS at open and close time. 





OVR XAl Auxiliary Access Blocks (XABs) - used to 
transmit information on the keys for 


indexed files to RMS at open time. 





OVR | SWT COBOL switches flag PSECT. Indicates 
whether COBOL switches are referenced in 
the COBOL program. 


CON IFl Internal File Access Blocks (IFABs) - used 
internally by RMS to store information. 


| 

| 

| OVR FAIL File Access Block (FAB) - used to transmit 
CON IRI Internal Record Access Blocks (IRABs) - 

used internally by RMS to store 

information. 

CON KD1 Internal Key Descriptors - used internally 

by RMS to store information on the keys for 

indexed files. 





CON BDI Buffer Descriptor Blocks (BDBs) - used 
internally by RMS to store information on 
the buffers. 











COMPILER GENERATED PSECTS 


Table D-2 (Cont.) 
PSECT Names Suffixes 


-suttix | content 





Allocation 
















Key Buffers - used internally by RMS to 
store keys for indexed files. 













FDA Index Vector - contains address of 
first FDA in program. 


Note: 
OVR indicates overlayable PSECT. 


CON indicates concatenatable PSECT. 


APPENDIX E 


SORTING FILES IN A COBOL PROGRAM 


Files prepared for or.by COBOL programs may be sorted using the SORT 
utility, which is discussed in the PDP-1l SORT Reference Manual. A 
Major portion of that facility is available to the COBOL programmer 
through usage of a set of subroutine linkages, described in detail in 
this chapter. All such linkages involve use of a CALL statement with 
an appropriate parameter list. 


E.1 CALL STATEMENTS REQUIRED 


A set of five CALL statements, each calling a particular SORT 
subroutine, is required within a COBOL program in order to produce a 
sorted output file. Each of these subroutines (RSORT, RELES, MERGE, 
RETRN, ENDS) performs a specialized function in the SORT procedural 
seguence and lets the COBOL programmer both specify sorting parameters 
and perform special operations on individual records as they pass 


through the initial and final phases. 


E.1.1 Initializing the SORT - CALL RSORT 


The following statement is needed to initialize the sorting operation: 


CALL "RSORT" USING IERROR, KEYSIZ, MAXREC, KEYLOC, SRTBUF, 
BUFSIZ, SCRNUM. 


Parameter usage is as follows: 


IERROR - location in which a SORT subroutine may place a 
non-zero error code, if necessary, in COMP form, 
value less than 100. 

KEYSIZ - location containing byte count of total key size 
in COMP form, a positive even integer. 

MAXREC - location containing byte count of maximum data 
record size in COMP form, a positive even integer. 
The sum of KEYSIZ and MAXREC cannot exceed 16,383 
(decimal). 

KEYLOC - address of most major word in key. See Section 
E.2 for details on setting up sort key. 

SRTBUF - address of first word in sort work area. 

BUFSIZ - location containing byte count of sort work area 


size in COMP form. 


B= 1 


SORTING FILES IN A COBOL PROGRAM 


SCRNUM - location containing number of scratch files 
available to the SORT (not less than 3, not more 
than 8), in COMP form. 


E.1.2 Passing a Record to the Sort - CALL RELES 
The following statement is needed to pass a record to the sort: 
CALL "RELES" USING IERROR, RECSIZ, INREC. 
Parameter usage is as follows: 
IERROR - usage is as described above. 
RECSIZ - location containing byte count of data record size 
in COMP form, a positive even integer not greater 


than value in MAXREC. 


INREC - address of record to be passed to the sort. 


E.1.3 Merging the Scratch Files - CALL MERGE 


The following statement is needed to merge the scratch files in the 
sort after all input records have been passed to the sort: 


CALL "MERGE" USING IERROR. 


IERROR usage is as described above. 


E.1.4 Requesting an OUTPUT Record - CALL RETRN 


The following statement is needed to request the output records, one 
at a time, produced in sorted order by the sort: 


CALL "RETRN" USING IERROR, RECSIZ, OUTREC. 
Parameter usage is as follows: 
IBRROR - usage is as described above. 
RECSIZ - Todation to receive byte count of returned data 
record size in COMP form, a positive even integer 


not greater than value in MAXREC. 


OUTREC - address of area to receive returned data record. 


NOTE 


RETRN indicates "no more records" by 
placing a negative value in IERROR. 


SORTING FILES IN A COBOL PROGRAM 


E.1.5 Terminating the Sort - CALL ENDS 


The following statement is needed to terminate the sort after all 
sorted output records have been returned: 


CALL "ENDS" USING IERROR. 


IERROR usage is as described above. 


E.2 SETTING UP THE KEY 


Before CALL RELES is executed, the COBOL programmer must first set up 
the key in an area outside the record itself. Since the key area must 
begin and end on a word boundary, usage of an 01 level description in 
the Working - Storage Section is recommended. The most major byte for 
the key, that byte "on the left", must be stored in the highest memory 
location of the key area, and the most minor byte, that byte "on the 
right", must be stored in the lowest memory location. 


Thus the data must be moved byte by byte, NOT word by word, to the key 
area, resulting in the key being stored "backwards" by bytes. If the 
actual key contains an odd number of bytes, the last unused position 
must be zeroed out, to insure proper results from word compares. Thus 
for a key of 7 bytes, KEYSIZ - 8; the contents of the lowest byte 
address snould always be zero, 


The form of the comparison is logical, i.e., all eight bits of a byte 
are significant; there is no implied sign. The programmer is 


responsible for organizing the key data passed to the sort in a form 
which ensures the correct sequence. 


E.3 WORK AREA SIZE 


The size of the sort work area, BUFSIZ, must be at least as large as 
the result of the following calculation: 


Minimum BUFSIZE = SCRNUM * (1110 + MAXREC + KEYSIZE) 
If less space is provided, the sort will keep decreasing the number of 
work files until either the above equation is satisfied or the number 
of files drop below three; the latter is an error condition (error 
code 17). 


Any extra memory will be used to expand the in-core sort area. Thus, 
in general, the more space supplied, the faster the sort. 


E.4 TYPICAL USAGE SEQUENCE 

Sort the file SORT-IN to produce the file SORT-OUT. 
1. Open SORT-IN. 
2. Call RSORT to initialize the sort. 


3. Read the next logical record from SORT-IN. If no more data, 
go to step 7. 
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4. Perform any desired operations upon the input record. If it 
is not to be submitted to the sort, go to step 3. 


5. Set up the keys from the new record. 


6. Call RELES to give the record to the sort, then loop back to 
step 3. 


7. Close SORT-IN. 


9. Open SORT-OUT. 


10. Call RETRN to get the next sorted output record. If no more 
records, go to step 13. 


ll. Perform any desired operations upon the sorted output record. 
If it is not to be included in the SORT-OUT file, go to step 
10. 


12. Write the record onto SORT-OUT, then loop back to step 10. 
13. Close SORT-OUT. 


14. Call ENDS to clean up the sort scratch files. 


E.5 LINKING SORT ROUTINES WITH A COBOL PROGRAM 


The actual sorting subroutines are contained in SORTS.OBJ and 
SIORMS.OBJ which are included in the COBOL object library (COBLIB). 
The programmer can link these to his own calling program, by following 
the usual procedure for using the Task Builder to task-build any COBOL 
program. 


Note that the sort subroutines use LUNs 5, 6, ... 12 for the scratch 
files. Use the task builder device assignment (ASG) command 
appropriately. The LUN can be overridden by globally patching 
location $RFIRL. Insure that the LUNS used by the sort subroutines do 
not conflict with the LUNs assigned to files in the COBOL program that 
might be open when the sort subroutines are called. 


E.6 COMPARISON WITH ANS COBOL SORT VERB 


Readers familiar with the ANS COBOL SORT verb will recognize that a 
substantial portion of that capability has been described in this 
chapter. The following points of comparison will be helpful in 
converting from such usage to the described facility: 


1. INPUT PROCEDURES are available thru the CALL RELES usage. 
2. OUTPUT PROCEDURES are available thru the CALL RETRN usage. 


3. Only ASCENDING keys are supported. The programmer can get 
the effect of DESCENDING key fields by simply complementing 
them when he stores them in KEYLOC. Note that the data 
record itself is unaffected by this procedure, so restoration 
of such fields after the sort is unnecessary. 
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The COLLATING-SEQUENCE option is not directly available. 
Again, however, the programmer could transform key fields 
when storing them in KEYLOC to achieve the desired effect. 


There is no MERGE feature, 


Multiple usages of the sort may occur within a given COBOL 
program provided that "RSORT" and "END" bracket each usage. 


There is no restriction on the presence of COBOL code in 
addition to INPUT and OUTPUT PROCEDURES. 


E.7 ERROR CODES 


Whenever 


location 


the sort detects an error, it returns a non-zero code to the 
specified by the programmer (IERROR in discussion above). 


The error codes (octal representation) and their meanings are: 


DEC 


10 


ll 


12 


13 


OCTAL 

00 No errors 

01 Device input error 

02 Device output error 

03 OPEN INPUT failure 

04 OPEN OUTPUT failure 

05 Size of current record is greater than 
maximum size 

06 Not enough work area 

07 "RETRN" was called after it had exited with a 
negative error code (end of sort). 

10 SORT routine called out of order. The order 
of the calls must be RSORT, RELES, MERGE, 
RETRN, ENDS. 

11 Sort already in progress. To do a= second 
sort, ENDS must be called to clean up the 
first sort. 

12 Key size is not positive, SORTS detected a 
zero or negative key size in its calling 
parameter. 

13 Record size not positive. 

14 Key address not even. The keys must start at 
an even address (SORT uses word moves). 

15 Record address not even. 


DEC 


14 


15 


bo 
oN 


18 


19 
20 
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OCTAL 


16 


iS) 
co 


21 


22 


23 


24 


Scratch records will be too large. The size 
of the keys plus the size of the largest 
record must be less than 377776 (octal). 


Too few scratch files. A minimum of 3 
scratch files must be specified. 


a itch files. A maximum of 10 
atch files may be specified. 


=) 
kg 
in 
Q 
a) 
ey) 
rr 


End-of-string record was detected where none 
was expected. 


Like 21, but for End-of-File. 
SORT found a record larger than it expected. 


Record length is non-standard for SORTT, 
SORTA, SORTI. , 


[COMP items are displayed in DECIMAL! ] 


APPENDIX F 


RSTS/E TERMINAL HANDLING SERVICES 


The PDP-1ll COBOL runtime library contains a set of callable 
subroutines that support multi-terminal access from a single COBOL 
program. These subroutines run only on RSTS/E. 


The purpose of this subroutine package is to provide asynchronous 
terminal I/O support for COBOL programs running on RSTS/E. 


F.1 GENERAL SERVICES 








The subroutines provide the following services: 


l. The ability to assign and deassign available terminal 
(keyboards) to the running COBOL program. 


2. The ability to OPEN or CLOSE a specific I/O channel and 
logical unit pair for terminal input/output. 


3. The ability to WRITE a message to any single terminal 
assigned to the program. 


4. The ability to READ a message from a specific terminal. 


5. The ability to READ a message from any terminal in the group 
assigned to the program and have the subroutine identify the 
terminal from which the message came. This technique is 
known as polling. 


6. In conjunction with the unsolicited READ capabilities, 
ability to specify how long to wait for a message from any 
terminal before returning to the user program. 
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F.1.1 Open a Logical Unit for Terminal I/0 
This function must be called to initialize the multi-terminal 
subroutines to expect terminal I/O on a specified logical unit (LUN). 
Subsequent terminal I/O subroutines require the LUN to_ function 
properly. 
The form of the CALL is: 

CALL “KBOPEN" USING ERR, LUN 
Where: 


ERR ~- is a binary data item [PIC 9(4) COMP] that contains the 
returned error status code. (See Section F.2.) 


LUN - a binary data item [PIC 9(4) COMP] that contains’ the 
logical unit number to uSe. 


Example 


MOVE 14 TO LUN. 
CALL "KBOPEN" USING ERR, LUN. 


An error code of zero indicates a successful call. 


The choice of LUN number is very important and must comply with the 
following rules: 


1. It must be in the range of 1 to 15. 


2. It must not conflict with a LUN number assigned by the COBOL 
compiler to a file in the COBOL program. 


F.1.2 Close a Terminal Logical Unit 


This function disassociates a LUN and all keyboards assigned to it 
from the running COBOL program. The form of the CALL is: 


CALL "KBCLOS" USING ERR, LUN 


Where: 
ERR and LUN are as specified in 


KBOPEN 


F.1.3 Assign a Terminal 


In order to use the RSTS/E COBOL multi-terminal functions, each 
terminal must be assigned to the COBOL program. A CALL is made to the 
subroutine KBASGN to assign a specific terminal or keyboard (KB) to a 
logical unit {(LUN). This LUN must have been the subject of a 
previously executed CALL to KBOPEN in the COBOL program. 


ty 
N 
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The form of the CALL is: 


CALL "KBASGN" USING ERR, KB-UNIT 


Where: 
ERR - A 2-byte binary data item [PIC 9(4) COMP] that contains 
an error code returned by the subroutine (see Section 
F.2). 


KB-UNIT - A 2-byte binary data item [PIC 9(4) COMP] that contains 
the keyboard number. 


F.1.4 Deassign a Terminal 


This function removes the specified terminal unit from the list 
assigned to the specified LUN. The form of the CALL is: 


CALL "KBDEAS" USING ERR, KB-UNIT 
Where: 


ERR AND KB-UNIT are as specified for the call to KBASGN. (See 
Section F.1.3.) 


F.1.5 Write to a Specific Terminal 


Assuming that the specified terminal has been assigned, this function 
delivers a message to it. The form of the CALL is: 


CALL "KBWRIT" USING ERR, COUNT, MESSAGE, LUN, KB-UNIT 


Where: 
ERR - the 2-byte binary data item as specified earlier. 
COUNT - a 2-byte binary data item [PIC 914) COMP] that contains 


the length of the message in bytes. 


MESSAGE - the data item that contains the message to be written. 
This message must contain all vertical and horizontal 
formatting characters such as carriage returns, line 
feeds and tabs. 


LUN - a 2-byte binary item [PIC 9(4) COMP] as_ previously 
specified. 


KB-UNIT - a 2-byte binary data item [PIC 9(4) COMP] identifying 
the specific terminal to which the message is written.. 
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F.1.6 Read from a Specific Terminal 

This function allows a COBOL program to read a message from a specific 
terminal. If a terminal operator types CONTROL-Z at a terminal, error 
code 11 (end-of-file on device) is returned. The form of the CALL is: 


CALL "KBREAD" USING ERR, COUNT, MESSAGE, LUN, KB-UNIT 


Where: 
ERR - is the 2-byte binary data item into which a 
success/error code will be returned. 
COUNT - is the 2-byte binary data item which contains’ the 


length of the message just read. Before execution of 
the CALL, this data item must contain the maximum 
record length. 


MESSAGE - defines the data item into which the message is’ read. 
This data item should be long enough to contain the 
longest anticipated message to be read. 


When a message is read from a terminal, the message is 
prefixed by a l1-byte field which contains the terminal 
unit number in binary. Therefore, reserve space in the 
message input data item for this byte. 


i.e., 


§1 MESSAGE 
@2 KB-NUM PIC X. 
@2 REAL-MESSAGE PIC X(8@) 


All messages are returned as ASCII strings with no 
conversions taking place. 


LUN - a 2-byte binary data item containing the LUN number. 


KB-UNIT - a 2-byte binary data item containing the terminal 
number to be used in the READ. 


F.i.7 Read Unsolicited from any Terminai Assigned 


This function allows a COBOL program to read a message from any 
terminal assigned to the program. The read is called unsolicited 
because no specific terminal is identified. The program reads a 
message from the first terminal found to have typed in a message. 
This function can also wait for input from a terminal for a_ specified 


length of time - up to 255 seconds. If no message is available from 
any assigned terminal within this time, then an error condition is 
returned. The error code is 13 - a user data error on device 


condition that is generated by the RSTS/E monitor. 


Using this function, the COBOL program can effectively poll a group of 
terminals, requesting input. 
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The form of this CALL is: 


CALL 


Where: 


Fe2 


ERR, 


"KBREAU" USING ERR, COUNT, MESSAGE, LUN, KB-UNIT TIME 


COUNT, MESSAGE, and LUN are as specified in the description 


of KBREAD tSee Section F.1.6.), 


and 


KB-UNIT is a 2-byte binary data item that contains (upon return 


TIME 


from the call to KBREAD) the unit number (in binary) of 
the terminal from which the current message was read. 


- is a 2-byte binary data item containing a value from 1 
to 255 which is the amount of time in seconds to wait 
for input from the terminal(s). If no message is 
available in this time, an error 13 {user data error on 


me RA 


device) is returned. 


wait indefinitely for input from the terminal(s). 


Tf TIME is given a zero value, then the system will 


ERROR CODES DURING MULTI-TERMINAL HANDLING 


These values are returned in binary in the 2-byte data item used in 
every call to the multi-terminal subroutines. 


CODE 


11 


12 


MEANING 


Successful. 


NOT A VALID DEVICE. An attempt was made to write to an 
unassigned device with KBWRIT. 


I/O CHANNEL ALREADY OPEN. A KBOPEN call attempted to use a 
LUN that was already in use by the program for a file or for 
other terminal operations because of a previous KBOPEN call. 


DEVICE NOT AVAILABLE. A KBASGN call was made to assign a 
terminal that is unavailable to the program and is reserved 
by another user. 


I/O CHANNEL NOT OPEN. A call to KBASGN, KBREAD, KBREAU or 
KBWRIT was made using a LUN that was not opened by a KBOPEN 
call. 


END OF FILE ON DEVICE. A user at an assigned terminal typed 
CONTROL/Z during a KBREAD call. 


FATAL SYSTEM I/O FAILURE. A system level I/O error occurred 
- the user has no guarantee that the last operation was 
performed. 


13 


15 


31 
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USER DATA ERROR ON DEVICE. Bad data may have been 
transmitted during the previous I/O call or a call to KBREAD 
or KBREAU did not get any data in the requested wait time. 


KEYBOARD WAIT EXHAUSTED. The wait time requested for input 
during a KBREAU call has passed with no input. 


ILLEGAL BYTE COUNT FOR I/O. A bad message length value was 
used as a parameter during a KBWRIT call. 
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SOURCE PROGRAM LISTINGS 


This appendix contains compiler listings for two COBOL programs. The 
first, STATB, calls three subprograms; the second, DOCATS, is one of 


the 


The 
as: 


The 


subprograms. 


examples demonstrate some of the features of PDP-11 COBOL, such 


e The COPY statement 

e The COPY REPLACING statement 

e Tne CALL statement 

e The results of using the /MAP and /OBJ compiier switches 
e PSECT names resulting from the /KER compiler switch 


circled numbers on the source listings indicate features that are 


annotated in the text. 


Source Listing Features 


The version of the PDP-11 COBOL compiler. 


The source file, including file type, or extension, and version 
number (for RSX-11M and IAS). 


Date and time when the compilation began. 


The compiler command line. The contents of the command line can 
help to explain why the listing looks like it does and how the 
program runs. For example, this command line shows that’ the 
/KER:ST switch was used; it explains why PSECT names contain the 
characters "ST". 


The IDENTification number assigned by the compiler. This number 
identifies the specific compilation of the program and is used in 
OTS error message displays. 


Source line number assigned by the compiler. This number is used 
in OTS error message displays to indicate the location at which 
the error was detected. It also appears in error message 
displays that show nested PERFORMs. 
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Sequence number. If the source file used conventional format, 
the sequence field (positions 1-6) appears here. 


Source text. This area contains the text that was processed by 
the compiler. If a line of text was too long, only the part that 
appears here wasS processed. The compiler also prints a 
diagnostic message when it truncates a line of source text. 


Identification field. If the source file used conventional 
format, this area contains the identification field (positions 
73-89). 


Identifies a source line that: a) contains a COPY statement, or 
b) was copied from a library file. 


COBOL Verb (appears only when /OBJ switch is’ used). Identifies 
the COBOL verb that is referred to by the other entries on the 
line. 


Segment number (/OBJ switch only). Identifies the program 
segment, or PSECT. Notice that this is not the PSECT name; it 
is a consecutive number assigned to all procedural PSECTS during 
compilation and duplicates the segment numbers in other programs. 


Offset (/OBJ switch only). Specifies the octal offset (distance) 
from the beginning of the segment for the object code generated 
by the COBOL verb (number 11). 


Compiler diagnostic severity code. Describes the seriousness of 
the compiler diagnostic. This diagnostic is "informational", 
which means that it probably does not indicate a_ serious 
condition. 


Diagnostic source line number. Identifies the source line to 
which the diagnostic applies. In this case, OPTIONS-AREA is 
defined as larger than CUSTOMER-FILE-ID; therefore, truncation 
occurs. 


Compiler diagnostic number. Identifies the specific diagnostic. 
Use this number to find a description of the diagnostic in 
Appendix H. 


Diagnostic message. A one-line description of the condition. 


FILE-TO-LUN ASSIGNMENT TABLE. This table appears for any program 
that contains file descriptions. 


File-name. The name that is used in the program to refer to the 
file. 


Source line. The file-description-entry appears on this source 
line. 


Relative LUN. Identifies the file by relative Logical Unit 
Number. This number can duplicate relative LUNs in other 
programs in the run unit, because actual LUNS are assigned by the 
Task Builder. 
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Data Map. Describes the data-names and file-names used in the 
program. This section appears only if the /MAP switch is used. 


Level. Contains the level-indicator or level-number of the item. 
An L preceding the level indicates that the data-name is a 
Linkage Section item. 


Name. The file-name or data-name. 


Source line. The file-name or data-name is defined on this 
source line in the Data Division. 


Data Division location. Identifies the octal offset of the file 
or data-name from the beginning of data PSECT SkkDAT (kk=kernel). 
For Linkage Section data-names, the offset is from the #l-level. 


Directory location. Identifies the octal offset of the data 
item's descriptor. For Linkage Section data items, the offset is 
from data PSECT SkkARG (kk=kernel); for other data items, the 
offset is from data PSECT $kkDDD. The OTS uses the descriptor to 
operate on a data item. 


A directory iocation that contains asterisks indicates that the 
compiler did not generate a descriptor because the data-name was 
not used in the Procedure Division. 


USAGE. Corresponds to the USAGE clause or implicit usage of the 
data item description. Thé following abbreviations are used: 


DISP DISPLAY 

CMP COMPUTATIONAL 
CMP3 COMPUTATIONAL-3 
CMP6 COMPUTATIONAL-6 
INDX INDEX 


Class. Identifies the COBOL class of the data item. The 
compiler determines class from the PICTURE or level associated 
with the data-name. The following abbreviations are used: 


ALPHA Alphabetic 
NUM Numeric 
AN Alphanumeric 


ANEDIT Alphanumeric Edited 
NMEDIT Numeric Edited 


Occurrence level. Indicates the number of subscripts necessary 
to refer to the data-name. 


Length. Specifies the length of the data item in decimal bytes. 
Procedure Name Map. Describes the procedure-names that appear in 
the program. This section appears only if the /MAP switch is 


used. 


Procedure-name. This is the name as it appears in the Procedure 
Division. 


Source line. Identifies the source line in which the 
procedure-name is defined. 
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PSECT. Identifies the name of the executable code PSECT (program 
section) in which the procedure-name appears. 


Offset. Specifies the octal offset (distance) of the location of 
the procedure-name from the beginning of the PSECT. 


Segment-number. Corresponds to the segment-number in the header 
for the section in which the procedure-name appears. 


‘Section. An "S" indicates that the procedure-name is a 
section-name. 


Paragraph. A "p" indicates that the procedure-name is a 
paragraph-name. 


Segmentation Map. Describes the segmentation for each Procedure 
Division section. This map appears only when the /MAP switch is 
used. 


Section Name. The name of the section as it appears in the 
Procedure Division. 


Segment-number. The segment-number specified in the section 
header or the implied segment-number 99. 


PSECT Name. Indicates the name of the procedural PSECT generated 
for the section. If the generated code exceeds the code segment 
limit, the compiler generates additional PSECTs; their names are 
displayed beneath the first. The code segment limit can be 
changed by using the /CSEG switch. 

The size of the procedural PSECT in octal bytes. 

The size of the procedural PSECT in decimal words. 
Compiler-Generated PSECTs. Describes the procedural PSECT's 
generated by the compiler to provide run-time execution 
initialization. 

PSECT Name. 

The size of the PSECT in octal bytes. 

The size of the PSECT in decimal words. 


Referenced OTS Routines. Lists the names of all COBOL OTS 
routines that are referenced by the compiler-generated code. 


Data PSECT Map. Lists the nonexecutable PSECTs generated by the 
compiler. Appendix D describes the data PSECTs generated for 
each compilation. 

PSECT Name. 


The size of the PSECT in octal bytes. 
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The size of the PSECT in decimal words. 


External Subprogram References. Lists the names of all 
subprograms referenced by CALL statements in the program. 


Error Severity Code. Describes the seriousness of errors. 
Chapter 12 describes the severity codes and their meanings. 


Error Count. The number of errors detected in the compilation 
for each severity level. 


Compiler-generated ODL File. Lists the contents of the ODL file 
generated for this compilation. 
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COBOL 4,82 SRCrSTATS.CBL;4 


CMDISTATB, STATBSSTATB/MAP/OBJ/KERSST—_/G) mm @) 


IDENT: 278266 


Terrrerrerrrrerrrerrrrrerwre ee 
q he. = 


B5"OCT#78 36541313 PAGE O81 
as - | 


TOENTIFICATION DIVISION, 


PROGRAN@ID, STATB,. 
INSTALLATION, JONES MAIL ORDER COMPANY, 
DATE@=wRITTEN, 5 oct 1978, 
DATE=CGMPILED, 
25-OCT=76 . 
REMARKS, Using celled programs, this program demonstrates 


the effects and advantages of moduler program 
development, Denending en cperator=speci fied 
options and the contents of data records, the 
orogra™ generates various outputs. 


The called programs ares 
NAME FUNCTION 


EXCEPT Generates an exception report. 
DOocAaTS Generates mailing labela. 
CREDLM Generates “credit limit” lettera, 


ENVIRONMENT DIVISION, 


CONFIGURATION SECTION, 
SOURCE*COMPUTER, POP=11, 
OBJECT@COMPUTER, POP ej} 
SEGMENTeLINIT IS e5, 
INPUT*OUTPUT SECTION, 
FILE=CONTROL, 


SELECT CUSTOMER@FILE 
ASSIGN TO "SysCUSTOM,DAT" 
ORGANIZATION IS INDEXED 
ACCESS MODE IS DYNAMIC 
RECORD KEY IS CUSTeCUST=NUMBER 
ALTERNATE RECORD KEY IS CUST=CUSTOMER@NAME 
FILE STATUS IS CUSTOMER@=FILE=STATUS, 


SELECT STATEMENT@REPORT 
ASSIGN TO "SYISTATEM,REP® 
FILE STATUS IS STATEMENT@REPORT@STATUS, 
DaTa OIVISION, 
FILE SECTION, 
FD CUSTOMER@FILE 
LASEL RECORDS ARE STANDARD 
VALUE OF ID IS CUSTOMER@FILE@ID, 
coPy "CUSTRC,CPY* 


WEPLACING CUSTeOWEsAMT BY CUST@eCURRENT@BALANCE, 
CUST*BOUGHT BY CUST@PURCHASES@=YTD, 


Zi CUSTOMER@FILE@RECORD, 


03 CUST@CUSTeNUMBER PIC X(6), 
03 CUST@CUSTOMER@NAME PIC X(30). 
@3 CUST*ADDRESSaLINEo) PIC X(38),. 
3 CUST*A4DDRESSeLINE#2 PIc X(3@). 
23 CUST@ADDRESS@LINES3 PIC x(3¢), 
03 CUST=ADDRESS#ZIP#CODE PIC x(5),. 
23 CUST@PHONE, 
as CUS TePHONE@ARE ARC ODE Pte ESI. 
es CUS TePHONE@EXCHANGE PIC x(3), 
es CUST@PHONE@LASTo4 PIC 9(4), 
a3 CUST@PHONE NUMBER 
REDEFINES CUST=PHONE PIC 9(18), 
@3 CUST*ATTENTIONeLINE PIC x(20), 
a3 CUST#=CREDIT#=LIMIT PIc 9(12)¥99, 
a3 CUST=HEADER@DATA REDEFINES CUSTeCREDITeLIMIT, 
a5 FILLER PIC x(6). 
as NEXT*ACCT=NUMBER PIC 906). 
a3 CUST@=CURRENT@BALANCE 
PIC 9(18)V99, 


L @2a76 
L 82077 
L 02078 
L eaa79 
L aaa? 
B88) 
2208e 
22083 
@@084 
00285 
@3086 
20287 
8388 
94489 
O8890 
@02891 
oa292 
84093 
@ea94 
82095 
A096 
68097 
@8298 
62299 
42190 
@B18t 
00102 
Seig3 
galna 
gatas 
20106 
80127 
aoie08 
@@1a9 
9@119 
9@111 
@0112 
28113 
@ei1a 
@8115 
@2116 
88117 
00118 
08119 
aei2a 
O8l121 
98122 
92123 
@2124 
@9125 
@9126 
02127 
220128 
ae1es 
00130 
00131 
00132 
02133 
88134 
02135 
00136 
00137 
08136 
08139 
20149 
90141 
@@142 
Q8143 
@8144 
06145 
@2@146 
@6147 
80148 
aa149 
80150 
00151 
@81S2 
22153 
80154 
88155 
@0156 
08157 
90158 
BQ159 
06160 
@6161 
82162 
@2163 
08164 
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@3 CUST*PURCHASES@YTD 
a3 CUST@NEXTeORDER@SEQUENCE 
a3 CUST#NEXT@PAYMENT@SEQUENCE 


FO STATEMENT@REPORT 
LABEL RECORDS ARE STANDARD, 
@1 ST&ATEMENTeREPORT*RECORD, 


@3 FILLER PIC 
@3 AaDDRESS=wINDOW PIC 
@3 FILLER PIC 
@3 ADORESS=ZIP PIC 
@3 FILLER PIC 
B3 FORMeNAME, 
@S5 FILLER PIC 
@5 FORMeDATE PIC 
@i S#ReRe?, 
93 FILLER PIC 
@3 REPORT*CREDIT PIc 
63 FILLER PIC 
@3 REPORT*YTD PIc 
21 SeReRes, 
@3) STATEMENT@DATE PIC 
@3 FILLER PIc 
23 STATEMENT@CAPTION PIC 
@3  STATEMENT=BALANCE PIC 
WORKINGeSTURAGE SECTION, 
@1 CUSTOMER@FILE=STATUS PIC 
@1 STATEMENT@REPORTeSTATUS Pic 
@1 CUSTOMER@FILE=I0 PIC 
VALUE "SYsCUSTOM,DAT", 
@1 TODAYS@DATE PIC 
@1 TDR REDEFINES TODAYSeDATE. 
23 «TODAYeYEAR PIC 
@3 TODAY=MONTH PIC 
63 TODAY*DAY Pic 
@1 TODAYS@REPORT=DATE, 
@3 TODAYsMONTH PIc 
@3 FILLER PIC 
a3 TODAYeDAY PIC 
@3 FILLER PIC 
3 TODAY=YEAR PIC 
Ot STANDARDe MESSAGE PIC 
@1 DISP=“ESSAGE. 
63 FILLER PIC 
@3 DISPeNUM PIC 
Zi YTOsCATALOGeMINIMUM PIc 
@1 EXCEPTION@INDICATORS, 
@3 EXCEPTION@eINDICATOR OCCURS 14 
21 OPTIONS@A4REA, 
63 OPTIONS#AREACHAR OCCURS 32 
@1 A@COUNT PIC 
@1 OPTION@STORAGE, 
@3 OPTION*ENTRY OCCURS 8 
@1 OPTION@VALUES REDEFINES OPTION@=STORAGE, 
23 FILLER 
88 WANTeSTATEMENTS VALUE 1 
@3 FILLER 
88 wWANT* INVOICES VALUE 1 
@3 FILLER 
88 WANT@ALL@CATALOGS VALUE 1 
@3 FILLER 
68 wANT@SOME*CATALOGS VALUE 1 
@3 FILLER 
8B WANT@CREOITeLIMIT@LETTERS VALUE 
@3 FILLER 
@1 RECGRDeCOUNT PIC 
G1 STATEMENT*COUNT PIC 
@1 INVOICE*COUNT PI¢ 
@1 CREDITeLIMIT=COUNT PIC 
@1 CATALOGeCOUNT PIC 


PROCEDURE DIVISION, 
DECLARATIVES, 
CUSTOM@ERROR SECTION, 


PTC 9(18)V99. 
PIC 9(4), 
PIC 9(4), 


x(5). 
x(30), 
XC1). 
x(5), 
x(25). 


X(6). 
x(8), 


XC15)6 
2,222,227 4229.99, 
XC13), 

292276222 ,729499, 


X12). 
X(18). 
X32), 


7.7779 7 aa 
aPCeeeee 7 


I7a 
F7eeTeT7E 


XC2). 
x2), 
X€14) 


9(6). 


9(2). 
9(2). 
$(2). 


Z9, 

X(1}) VALUE "/*, 
902), 

X€1) VALUE "7", 
92). 


X(Sa) VALUE SPACES, 


X(38) 
Z(5), 


VALUE SPACES, 


9(18) VALUE 12000, 


PIC 9(1), 
PIC X(1), 
92). 

PIC 901), 
PIC 91), 
THRU 9, 

PIC 9(1), 
THRU 9, 

PIC 9(1), 
THRU 9. 

PIC 9(1), 
THRU 9, 

PIC 9(4), 
{ THRU 9, 

PIC x(3), 


9(S) VALUE 2, 
9(5) VALUE 8, 
9(5) VALUE 2, 
9¢5) VALUE 2, 
9¢5) VALUE @, 


USE 


DISPLAY 


USE 


DISPLAY 


stop 


ACCEPT 
MOVE 


MOVE 


DISPLAY 
ACCEPT 
IF 


MOVE 


Pp 


1 @0199 as7i 


MOVE 


DISPLAY 
DISPLAY 
DISPLAY 
DISPLAY 
DISPLAY 
DISPLAY 
ACCEPT 
MOVE 

IF 
DISPLAY 
GO 

MOVE 


3 


a} 


@e2 


b2 


Be 


@3 
3 
@3 


a3 
a3 
a3 


5 


@3 


a3 
@3 
03 
@3 
@3 
a3 
a3 
a3 
83 
a3 
23 
23 


@ 


@2d0e6 


BABABSE 
420032 


BBd206 


2eB206 


200033 


wganre 
e2a826 


geese 


eoer72 
@@a1ia 
obslee 


200136 


P 


POSSIBLE 


deeide 


BPB156 
282174 
oesele 
O40es0 
eeneue 
BAd264 
280302 
800314 
204324 
o26354e 
BA2356 


223366 


SOURCE PROGRAM LISTINGS 


BALES 
¥a166 


2AL67 
20168 
28169 


aB172 
OB174 
e172 


@O173 
@a17a 


oB175 
20176 
@el77 


80178 
@8179 
aG18G 
O2184 
@@182 
Wa1as 
@2184 
82185 
02186 
20187 
wA188 


@3189 
a2190 
2019) 
@6192 
aa193 
o8194 
QA195 
Be196 
a2i97 
20198 


Oe199 


USE AFTER STANDARD ERROR PROCEDURE ON CUSTOMER@FILE, 


SBEGIN, 


DISPLAY "Ie0 ERROR ON CUSTOMER=FILE, CODE (* 
CUSTOMER@FILE=STATUS 


")*, 


STOP RUN, 


STATEM#ERROR SECTION, 


USE AFTER STANDARD ERROR PROCEDURE ON STATEMENT@REPORT, 


SBEGIN, 


DISPLAY "IeO ERROR ON ST 
STATEMENT*#REPORT#STA 


LO ele 


ATEMENT@REPORT, CODE (* 
Tus 


STOP RUN, 


END DECLARATIVES, 


FR TR RT TRI RRO RR TO TORI EER RRR ERI 


This section performs housekeeping 
functions ontye 


START#UP*HOUSEKEEPING SECTION 49, 
SBEGIN, 


ACCEPT TODAYS#DATE FROM DATE, 
MOVE CORRESPONDING TDR TO TODAYS@eREPORT@DATE, 
MUVE SPACES TO OPTIONS@AREA, 

Get CUSTOMER=FILE mame. Use default 

if none is entered, 
DISPLAY *" ENTER CUSTOMER FILE NAME COR CR)", 
ACCEPT OPTIONS@AREA, 
IF OPTIONS=#=AREA NOT & SPACES 

MOVE OPTIONS@AREA TO CUSTOMER@FILE@ID 


MIGH ORDER RECEIVING FIELD TRUNCATION, 


28280 
eeeat 
GB22e2 
“8203 
agee4 
88285 
22206 
ev2u7 
20298 
88209 
B8218 
a92i1 
agate 
83213 
aaela 
82215 
Q¥216 


a4217 


MOVE SPACES TO OPTIONSwAREA, 
Get options from the operator and 


store results, Ignore nonestendard 
option input. 


OISPLAY " ENTER OPTIONS?*®, 
DISPLAY *" § & Print statements". 
DISPLAY " I s Print invoices", 
DISPLAY " CA @ Maj} all catalogs". 
OISPLAY " CO m3 Mail selective cataloga", 
DISPLAY " CL # Credit limit letters”, 
ACCEPT OPTIONS@ANEA, 
MOVE ALL ZERO TO OPTION@#STORAGE, 
IF OPTIONS@#AREA = SPACES 
DISPLAY "Discrepancy Report Only" 
GO TO CONFIRM*OPTIONS, 


MOVE @ TO AwCOUNT, 


INSPECT 


IF 
OISPLAY 
STOP 


DISPLAY 
IF 
OISPLAY 
TF 
DISPLAY 
IF 
OISPLAY 
TF 
DISPLAY 
IF 
DISPLay 


DISPLAY 
ACCEPT 
IF 

GO 

IF 


DISPLAY 
STOP 


IF 
DISPLAY 
MOVE 


TF 
OISPLAY 
ACCEPT 


OPEN 
MOVE 
START 


OPEN 


READ 


GO 


a 


83 


a3 
@3 
63 


83 
a3 
83 
3 
83 


a3 
83 


a3 
63 
83 


@3 
a3 
63 


@3 
3 
Q3 


@3 


64 


4 


828376 


083566 
620682 
800622 


@@a624 
B28642 
888672 
680710 
888740 
098756 
881805 
aeiaed 
601054 
081872 
3e1!22 


061146 
B81164 
881176 
21246 
821256 


061276 
21314 


@81320 
021359 


801366 


061418 
201443 


801456 


OG1472 
88150 


601510 


001534 


800826 


888826 


SOURCE 


PROGRAM LISTINGS 


INSPECT OPTIONSeAREA TALLYING 
OPTION*ENTRY (14) FOR ALL "S*" 
OPTIONeENTRY (2) FOR ALL "I" 
OPTION®ENTRY (3) FOR ALL "CA" 
OPTION@ENTRY (4) FOR ALL "CO" 
OPTION@ENTRY (5) FOR ALL "CL", 

IF UPTION@STORAGE @ ALL ZERO 
DISPLAY “No options recognized" 


STOP RUN, 


DISPLAY "Selected options:", 
TF WANT@STATEMENTS 

DISPLAY " Statements", 
TF WANT INVOICES 


DISPLAY " Invoices". 


IF wANTeCREDIT*LIMITSLETTERS 
DISPLAY " Crecit limit letters®, 
CONFIRM@#OPTIONS, 
DISPLAY "CONFIRM OPTIONS: (YJes or (NJo", 
ACCEPT OPTIONS@AREA, 
IF OPTIONSeAREAeCHAR (1) NOT © PY" AND OAR 
GO 76 CONFIRMeOPTIONS, 
IF OPTIONS*AREACCHAR (1) = "N® 
OISPLAY "ABORTED BY OPERATOR" 
STOP RUN, 


IF WANT* INVOICES 
DISPLAY " INVOICES not implemented" 


MOVE @ TO OPTIONSENTRY (2), 


IF WANT@STATEMENTS 
DISPLAY "Enter statement message or CR" 


ACCEPT STANDARD@MESSAGE, 


OPEN INPUT CUSTOMER@FILE, 
MOVE “2@8680" TO CUSTeCUSTeNUMBER, 


START CUSTOMER=F ILE 
KEY IS > CUST@CUST*NUMBER, 


OPEN OUTPUT STATEMENT@REPORT, 
ARERR ERE RRA RE RRERREERERRAS AER EEE RRERERRRE EERE EES 


MAINLINE SECTION, 
SBEGIN, 


READ CUSTOMER@FILE NEXT 
AT END 


GO TO END=PROCESS, 


G-9 


ADO 


TF 
PERFORM 


add 


IF 


CALL 


ADD 


MOVE 
IF 
ROVE 


IF 


MOVE 
IF 
MOVE 
IF 
MOVE 
IF 
MOVE 
ELSE 
IF 
MOVE 
IF 


CALL 


IF 


Go 


GO 


CALL 


ADD 


- 


a4 


a4 
Ba 


@4 


o4 


e4 


aa 


4 
ga 
oa 


gu 


ga 
e4 
ga 
a4 
a4 
a4 
o4 
pa 
au 
ea 
a4 


@4 


a4 


o4 


ou 


ea 


Qua 


620836 


O20046 
agesee 


Q8O976 


@2d196 


BAseb2 


e@a214 


eee2ed 
wsoes4 
¢2d250 


e@a272 


420322 
B2a344 
603363 
320492 
BoR416 
eegaga 
avvasa 
adB476 
aeasdo 
ga0534 
v70556 


saas7e 


2694526 


202664 


e2do74 


ave7Le 


gee7ed 


SOURCE PROGRAM LISTINGS 


vel3ae 
Q8323 
94384 
He325 
Q6306 
8347 
8e3es 


BES“S 
OG31u 
oe3il 
ga312 
06313 
vesia 
aesis 


84316 
eo317 
WA3L8 


0319 
arsed 
0321 
ae322 


82323 
avseg 
@4325 


#2326 


88327 


ca 


4 ee OH 


+e 


see eH 


* 


ADD 1 TO RECORD*COUNT, 


Print statement if required, 


IF CUST=CURRENTeBALANCE > @ 


Sra ara, 


PERFORM PRINT@STATEMENT 
4D0 | TO STATEMENT@=COUNT, 
If we need a mailing label for 


a catalog, orimt ite 


IF WANT@ALL@ CATALOGS 
OR 
HANT@SOMEsCATALOGS 
AND 
CUSTePURCHASES@YTD NOT < YTDeCATALOGeMINIMUM 
CALL "DOCATS"™ USING CUSTOMER@=FILE@RECORD 
ADD 4 TO CATALOG=COUNT, 
Check for discrepancies {nm the 
customer’s record, 
MOVE ALL ZERO TO EXCEPTION@ INDICATORS, 
IF CUST=CUSTOMER@NAME = SPACES 
MOVE 1 TO EXCEPTION@INDICATOR (1), 


IF CUST*ADORESSeLINE@{ = SPACES 
OR CUST#ADDRESS@ZIPSCODE NOT > "28820" 


MOVE 1 TO EXCEPTION@INDICATOR (2). 
IF CUST*PHONE = SPACES 
MOVE 1 TO EXCEPTION@INDICATOR (3). 
IF CUST@CREDIT=LIMIT NOT > @ 
MOVE 1 TO EXCEPTION@ INDICATOR (4). 
IF CUST*CURRENT@BALANCE >» CUST@CREDIT#LIMIT 
MOVE 1 TO EXCEPTION@INDICATOR (8) 
ELSE 
IF CUST*CURRENT@SALANCE > CUST@CREDIT*LIMIT * 8.8 
MOWE | TO EXCEPTION@=INDICATOR (6), 
IF EXCEPTION@INDICATORS NOT @ ALL ZERO 


CALL "EXCEPT" USING CUSTOMER@=FILE#RECORD 
EXCEPTION@ INDICATORS, 


Generate a “credit limit letter’ 


if the customer has exceeded or 
{a about to exceed his Timit, 


IF WANT@CREDIT@LIMIT@LETTERS 
4ND 
CUST@CURRENT@BALANCE NOT < CUST@CREDIT=LIMIT * 3,8 
GO TO DO#CR, 


Go get the next record. 


GO TO MAINLINE, 

DO=CR, 
CALL "CREODLM" USING CUSTOMER@FILE#RECORD, 
ADD 4 TO CREDIT#LIMIT#COUNT, 


G-10 


SOURCE PROGRAM LISTINGS 


GO 2: 24 680734 
@0328 GO TO MAINLINE. 
82329 
ACZS3E RTT TT TIKIT RE EEE EERE RRR EROS 
40331 * 
00332 * The CUSTOMER@FILE has been completely 
06333 x processed, Report significant counts. 
@a334 * 
@8335 
@2336 END@PROCESS SECTION 47, 
62337 SBEGIN, 
CLOSE : 25 880826 
62338 CLOSE CUSTOMER@=FILE, 
CLOSE 2: 85 9@@816 
62339 CLOSE STATEMENT#REPORT, 
MOVE : @S @8d02e 
eusae MOVE "RECORD COUNT" TO DISPeMESSAGE, 
MOVE 2: 25 280236 
2341 MOVE RECORDeCOUNT TO DISPeNUM, 
DISPLAY : @5 eagase2 
@9342 CISPLAY DISP=MESSAGE, 
MOVE : 85 @@ua7e 
@¢343 MOVE "STATEMENTS" TO DISPeMESSAGE, 
MOVE : 85 4280102 
B4sa4 MOVE STATEMENT*COUNT TQ DISPeNUM, 
DISPLAY : 8S 8@0114 
o0385 DISPLAY DISP=HESSAGE, 
MOVE : 8S 986132 
O4346 MOVE "INVOICES" TO DISP=MESSAGE, 
MOVE : 85 @@@142 
@2347 MOVE INVOICE=COUNT TO DISP#NUM, 
DISPLAY : 25 @69a1S6 
Oo348 DISPLAY OISPeMESSAGE, 
MOVE 3 25 g@9174 ; 
3469 BOVE "CATALOGS" TO DISP=HESSAGE, 
MOVE 3 65) g0eee4 
68352 MOVE CATALOGeCOUNT TO DISP=NUM, 
DISPLAY 1: 85 @a@22a 
82351 DISPLAY DISP=MESSAGE, 
MOVE : @5 088236 
e8352 MOVE "CREDIT LIMIT LETTERS" TO DISP=MESSAGE, 
MOVE : 85 488246 
@3353 MOVE CREDIT*LIMIT=COUNT TO DISP=NUM, 
DISPLAY 1 25 @82262 
aa3zsq DISPLAY DISP=MESSAGE. 
STOP + @5 9@e3ea 
68355 STOP RUN, 
6356 
@2357 FICO SIO IOI TORSO TORT TOIT TORII 
ae358 * 
30359 * This section generates a statement 
88362 * for the current CUSTOMER@FILE 
0636) * record, 
86362 * 
08363 
QB364 PRINT@STATEMENT SECTION 48, 
a@365 SBEGIN, 
MOVE 3 86 9880006 
22366 MOVE SPACES TO STATEMENTwREPORT@RECORD, 
MOVE 3 86 @00a16 
04367 MOVE "STATEMENT" TO FORMmeNAME, 
WRITE 3 @6 888626 
09368 WRITE STATEMENT*®REPORT#RECORD AFTER ADVANCING PAGE, 
MOVE 3 86 g0225a 
20369 MOVE SPACES TO STATEMENT@REPORT@RECORD, 
MOVE 2: 86 228060 
08372 MOVE CUSTeCUSTOMER|NAME TO ADDRESSewWINDOW, 
MOVE $ 86 @00870 : 
20371 MOVE "DATE" TO FORMm@NAME, 
MOVE : @6 @oa1e89 
@8372 MOVE TODAYS@#REPORTeDATE TO FORM@DATE, 
WRITE 2 @6 600112 
62373 WRITE STATEMENT@REPORTeRECORD AFTER ADVANCING 1 LINE, 
MOVE & 86 086134 
@a374 MOVE CUST#ADDRESSeLINE@1 TO ADDRESSewWINDOW, 
MOVE : 26 @@u14d : 
88375 MOVE "ACCT3" TO FORM@NAME, 
MOVE 2 06 a2visa4 
88376 MOVE CUST=CUST=NUMBER TO FORM@#DATE, 
WRITE 2 86 B8vto4 
00377 WRITE STATEMENT*REPORT*®RECORD AFTER ADVANCING 1 LINE, 
MOVE 3 86 e218 
09378 MOVE SPACES TO STATEMENT@REPORT@RECORD, 
MOVE 2 @6 o@@e2en 
88379 MOVE CUSTeADDRESSeLINEs2 TO ADDRESS@WINDOw, 
WRITE : 86 g88e38 
82388 WRITE STATEMENT*REPORT=RECORD AFTER ADVANCING {1 LINE, 


G=11 


MOVE 
MOVE 
WRITE 
MOVE 
MOVE 
MOVE 
WRITE 
MOVE 
MOVE 
MOVE 
MOVE 


WRITE 
MOVE 


IF 
MOVE 


ELSE 
IF 
MOVE 


ELSE 
MOVE 
WRITE 


EXIT 


@6 
86 
86 
86 
@6 
86 
6 
66 
66 
86 
@6 
@6 
86 
86 
96 


6 
66 
a6 


86 
26 


@6 


B6 


eegesa 
eeg264 
eeee74 
808320 
822330 
GBG344 
@2e360 
@00404 
evedia 
2884524 
o7eaade 
242450 
680474 
e8esua 


Q293S2¢ 


008534 
eegs4a 
@20566 


028576 
eaBeVv6 
eeageis 


e2g65e4 


SOURCE PROGRAM LISTINGS 


OO381 
26382 
00383 
88384 
0385 
22386 
08387 
08388 
00389 
82398 
20391 
ea3s2 
G@393 
@2394 


83395 
88396 


02397 
84398 


28399 
20408 


98401 
28462 
22493 
e8404 
B2495 


eo40n6 


MOVE CUST#ADDRESS=LINE®3 TO ADDRESS@WINDOW, 

MOVE CUSTeADDRESSeZIP=CODE TO ADDRESSeZIP, 

WRITE STATEMENT@REPORT*RECORD AFTER ADVANCING 1 LINE, 
MOVE SPACES TO STATEMENT@REPORTe@RECORD, 

MOVE CUSTeCREDITeLIMIT TO RESORT=CREDIT, 

MOVE CUSTePURCHASES@YTD TQ REPORT#=YTD, 

WRITE STATEMENT*REPORT@RECORD AFTER ADVANCING 8 LINES, 
MOVE SPACES TO STATEMENT@*REPORT#=RECORD, 

MOVE TODAYS*REPORT*DATE TO STATEMENT@DATE, 

MOVE CUST*CURRENT#=BALANCE TO STATEMENT@BALANCE, 

MOVE "BALANCE QUE" TO STATEMENT@CAPTION, 

WRITE STATEMENT*REPORT@RECORD AFTER ADVANCING 6 LINES, 
MOVE SPACES TO STATEMENT=REPORT=RECORD, 

IF CUST*CURRENT@BALANCE > CUST@CREDIT#=LIMIT 


MOVE "xx CREDIT LIMIT EXCEEDED wx* 
TO STATEMENT*REPORTeRECORD 


ELSE 
IF CUSTeCURRENT@BALANCE > CUST@CREDITSLIMIT « 8,8 


MOVE "CONSIDER AN INCREASED CREDIT LIMIT, " 
TO STATEMENT=REPORT@RECORD 


ELSE 
MOVE STANDARD@MESSAGE TO STATEMENT@REPORT@RECORD, 


WRITE STATEMENT®REPORT@RECORD AFTER ADVANCING & LINES, 


SEXIT. 


EXIT, 


G-12 


COBOL 


SOURCE PROGRAM LISTINGS 


4,a2 SRCISTATS,CBL 34 


@5=O0CT#78 


FILE*#TOeLUN ASSIGNMENT “ee 


wordi2;t3 PaGE B11 


DIR 
Loc 


/ 
Q52008 


GO@006 
806014 


USAGE 


NAME SOURCE RELATIVE 
LINE LUN 
CUSTOMER@FILE @ O4gai, 
STATEMENT*REPORT AAaBL Gaede, 
DATA MAP 

LEVEL 62) NAME SOURCE DOTV 
@4) @i™ Owe 
FO CUSTOMER*PFILE OOG47 pAvGgad 
ro STATEMENTSREP ORT 64961 42dBu0 
ot CUSTOMEKeF ILE*REC ORE 03456 ged726 
23 CUST@CUST=NUMBER 22957 aaa7res 
@3 CUSTeCUSTOMER*NAME 23958 6@e734 
GS CUSTeADDRESSeLINERj o4a55 aeuTTe 
3 CUST#ADDRESS@LINE@? @8260 92@1la3a 
23 CUST#ADDRESSaLINES? #4661 galaes 
B35 CUST@ADDRESSeZIP@CODE Q@@062 BAlles 
B33 CUST#PHONE 20063 661131 
5 CUST@PHONE*AREA@CODE 90364 901131 
WS CUSTePHONE@EXCHANGE 09665 081134 
@5 CUST©PHONE@LASToa O8266 G@41137 
B63 CUSTePRONESNUMBER @Q967 091131 
03 CUSTHATTENTION@LINE aaee9 031143 
@3 CUST@CREDITeLIMIT Q@BB79 @21167 
23) CUST=HEADEN*DATA @9671 831167 
2S NEXTeACCTNUMBER @O873 Ba1175 
@3 CUST*CURRENTeBALANCE 8074 w@1203 
03 CUSTePURCHASESaYTD 02076 Balai? 
BB CTCUSTeNEATWORDERMSEVUENCE GB676 BKH1233 
33 CUSTeNEXT@PAYMENTeSEQUENCE @82079 081237 
a1 STATEMENT@REPORT=RECORD e083 aal2d6 
43 ADDRESSeaINDOW 64085 a91253 
63 ADORESS=ZIP @@087 21312 
23) FORMeNAME 49089 621352 
@5 FORH=CATE 44991 201356 
@1 SeReRo?2 20093 91246 
B33 REPORT@CREOIT 88095 901265 
33) REPORT@YTO Q@8097 881317 
@1 SeReR=3 B4G99 BB1246 
23) STATEMENT=DATE arleea aaieds 
33 STATEMENT#CAPTION Q@Bi1e2 waters 
3 STATEMENT*BALANCE 8163 801334 
oi CUSTOMER@FILE@=STATUS Q@Bi1e7 @21379 
él STATEMENT@REPORT@STATUS 0@128 441372 
at CUSTOMER=FILE=ID B2129 881374 
61 TODAYS=DATE ABIL gai1ai2 
@1 TOR A112 891412 
43 TODAYeYEAR 09113 881412 
23 TODAY=MONTH @A114 AOL444 
33 TODAY@DAY 28115 301416 
@1 TODAYS=REPORT=DaTE @3116 921420 
43 TODAYeMONTH @4117 281422 
#3 TODAY*DAY BB119 931423 
03 TODAY*YEAR @4121 201426 
@1 STANDARD#@MESSAGE @2123 waiasa 
61 DISPeMESSAGE 89125 901512 
23 DISP=NUM Q@B1e7 841559 
61 YTD=eCATALOGeMINIMUM BA129 081556 
o1 EXCEPTION@ INDICATORS @BZi3st Ba1s7a 
D3 EXCEPTION@=INDICATOR B2132 821570 
@1 OPTIONS@#AREA 00134 WA16G2 
@3 OPTIONS@AREA@CHAR B8135 3Aloete 
ei A@COUNT 080137 21648 
1 OPTION@STORAGE @2139 221642 
23 OPTION*ENTRY 64148 681642 
é1 OPTIONe VALUES 03141 gal6de 
@i RECORDeCOUNT 08154 9@16S2 
a1 STATEMENT @COUNT @@15S Balb6e0 
B1 INVOICE@COUNT 98156 881666 
@1 CREDITeLIMITeCOUNT 80157 @2@1674 
@1 CATALOG@COUNT Q2158 d@i7ae 


G-13 


oeguce 
000230 
geaats 
aeeaus 
wvagse 
RaKREK 
REEKREK 
KREKKE 
KRERHKE 
KekKKK 
AGB868 
wekkaREEK 
RakRAK 
bed866 
282074 
REE 
kakkkn 
adatae 
200118 
2aALL6 
eavle4 
aeei3se 
KKK 
698146 
800146 
weaker 
6av154 
006162 
B@d17e 
Q00176 
o0a204 
@ee2l2 
PAb2)28 
080226 
080234 
Qa624e2 
280256 
200256 
B0b264 
2aae72 
200358 
200306 
099314 
age322 
0203308 
0230336 
goa3u4 
200364 
880372 
aaadie 
@20426 
2¥B426 
aK 
260534 
20a54e 
aeesse 
BeO556 
290564 


CLass O€C LEN 


@ @® 


AN 
AN 
AN 
aN 
AN 
AN 
AN 
AN 
AN 
AN 
NUM 
NUM 
AN 
NUM 
AN 
NUM 
NUM 
NUM 
NUM 


AN 
NMEDIT 
NMEDIT 
AN 

AN 

AN 
NMEDIT 
AN 

AN 

AN 

NUM 

AN 

NUM 
NUM 
NUM 

AN 
NMEDIT 
NUM 
NUM 

AN 

AN 


NMEDIT ¢ 


NUM 
AN 
NUM 
AN 
AN 
NUM 
AN 
NUM 
AN 
NUM 
NUM 
NUM 
NUM 
NUM 


Cs) 
a2 


62 
88 
ai 
vr") 
ai 
86 
ae 


a@ 
ae 
a0 
CT) 
89 
88 


6205 
6006 


NAME 


CUSTOM*ERROR 
SBEGIN 
STATEM@ERROR 
SBEGIN 


SOURCE PROGRAM LISTINGS 


SOGURCE 


@ac'™ 


START*UP=HOUSEKEEPING 


SBEGIN 
CONF IRM@ OPTIONS 
MAINLINE 

SBEGIN 

DO*CR 
ENU*PROCESS 
SHEGIN 
PRINT*STATEMENT 
SBEGIN 

SEXIT 


98164 
22166 
aat72 
BQ174 
23187 
48188 
Bead) 
42266 
8267 
ua3e5 
Q8336 
@8337 
98364 
aases 
204s 


PROCEDURE NAME nap —(32) 


6s) 


$sTaal 
S$STAG1 
sSTue2 
$sTee2 
$ST9a3 
$STAG3 
$ST¢a3 
$STuad 
$ST994 
$SToad 
$ST2a5 
SST@05 
SSTuRS 
SST@G6 
$STUO6 


@2206 4B 
C2b6¢6 BY 
eeares af 
BAGGG6 Ad 
90326 49 
B8onee 49 
@o1i46 ag 
@20006 a 
BUe226 Ba 
Bee712 Ga 
226086 47 
BQue46 47 
Q30006 48 
BB0006 48 
643654 48 


SEGMENTATION MAP 


SECTION NAME 


CUSTOM*ERROR 
STATEM*ERROR 


STARTUP eHQUSEKEEPING 


MAINLINE 
END@PROCESS 
PRINT=STATEMENT 


COMPILER GENERATED PSECTS 


Mane 4) SIZE 


SSTENT B4SA2e 


on™. 
REFERENCED OTS KOUTINES OO) 


SMGKE SXOPEN 
$XGO SXENDP 
SXINIT $CZDLT 
SCFSNE SCSTGT 
SMGLA SAAF 2D 


06408 


SXREDN 
SXSTPR 
$CGZLT 
SCZ0G6T 
SAMGA 


SEGMENT NO, 
@) i 


$SX4RIT 
SXINSH 
SCZDLE 
SCGZGT 
SSdIX1 


on" 


$SToa1 


$ST2a2 
§$7203 
$ST3aa4 
$STaas 
SSTae6 


$XSTAR 
SXINTG 
SCGZLE 
SMC AD 
SXPRF1 


$xCLOS 
§XINTO 
$CSTEQ 
SMJUSL 


SIZE 


880860 
488868 
@@157¢8 
a837728 
280332 
200072 


SXEACC 
SXACCS 
SCFSEQ 
SMCFST 


oe *) wo vv wu iv vu 


88024 
gee@e4 
Baad 
60252 
08108 
Bgeee 


SXEDIS 
S$XCALL 
SCSTNE 
SMGNG 


SOURCE PROGRAM LISTINGS 


DATA PSECT wae —(8}) 
nane (62) cS) SIZE 


SSTDAT 81742 = 9497 
SSTDOD @4g606 28195 
SSIPOT 322030 aaeie 
$STARG  gaeeer B2920 
SSTKRK 920186 22635 
SSTILIT 01322 00361 
SSTLTD 92552 218% 
SSILST 980206 8003 
SSIPFM = gau2i4 = uae 
SSTSOT  o28086 003 
SSTADT 920000 eeaa 
SSTUSE 999032 apel2 
SCBIOT 223134 spade 
SCBFAI aaai2e ees 
SCBXAL 820169 69856 
$S1I0B 23420 20768 
SCBIF1 @9e14@ agus 
SCBIRI aaaiee = @vase 
SCBKO oB¥1d0 = @ag4B 
$CBBD1 @00144 gues 
$CBK81 090182 © 9a32 
SCBFD1 vevae2 = ava 
sceswT  gageg2 avert 


EXTERNAL SUBPROGRAM REFERENCES 
DOCcATS EXCEPT CREOLM 


6 


SEVERITY ERRCR COUNT 


I 1 


COMPILER GENERATED ODL Fite —68) 


sCOBOL STANDARD GDL FILE GENERATED ON? @5"0CT=78 @6241813 
sCOBOBJSSTATB, OB 
sCOBKERSST 
sCOBMAIN 
PRMSREQSCIOALS 
PRMSREQZC 10033 
eNAME ST$247,GBL 
ePSECT $87495,G8L,1,R*,CON 
ST@47S3 ,FCTR «ST$Q47=SSTUG5 
eNAME $7$048,G8L 
ePSECT S$STG06,GBL,I,R4,CON 
ST2Z48S: ,FCTR xSTSU4BeSSTZU6 
eNAME STS049,G8L 
ePSECT $STG63,G68L,1I,R*,CON 
ST@4gs: ,FCTR #ST$049"$STA03 
STOVRSs ,FCTR ST8478,STA48S,STH49S 


SOURCE PROGRAM LISTINGS 


COBOL 4,82 SRCSDOCATS,CBL 74 @SeOCT#78 6848223 PAGE Bai 


CMDsDOCATS,DOCATSSDOCATS/MAP/OBJ/KER3 D0 
IDENT: 278¢68 


BAQAL IDENTIFICATION DIVISION, 

38B02 

eaaa3 PROGRAM@ID, 

BeOS : DOCATS, 

@neaS DATE@WRITTEN, 

BBLS 5 ocT 1978, 

82007 DATE=COMPILED, 

92008 ¥5"0CT#78 , 

80029 REMARKS, This sub=program prints a mailing label 

wPele for each CUSTOMER=FILE record passed from 

eAdit the calling programe 

auele 

DOALS ENVIRONMENT DIVISION, 

GOD14G : 

OBe15 CONFIGURATION SECTION, 

BAB16 

AGQIT SUURCE*COMPUTER, POP=11, 

@0318 OBJECT=COMPUTER, PDP#t1 

OU919 SEGMENT*LIMIT 25, 

BvD20 

Wed21 INPUT*#OUTPUT SECTION, 

vg22 FILE#CONTROL, 

Gveves SELECT LABEL@REPORT 

eeged ASSIGN TO "SY?LABEL,REP" 

vaR25 FILE STATUS IS LABEL*REPORT=STATUS, 

wAD]6 

G0027 DATA DIVISION, 

22028 

80229 FILE SECTION, 

ease 

PA831 FD LABELSREPORT 

dease LABEL RECORDS ARE STANDARD, 

O8a3s3 @L LABEL@REPORT*=RECORD PIC xX(4@), 

wdvda @1 L=eReDETAIL, 

BA935 @3 FILLER PIC X(34),. 

23836 93 LR=aCCOUNT PIC x(6), 

@AG37 21 LeReDETAIL*2. 

68038 3 FILLER PIC X(3e2), 

88039 03 LReZIP PIC X(S). 

aeaae 

PABaL WORKINGeSTORAGE SECTION, 

Beede 

gugas VL LABEL@“KEPORT=STATUS PIc x¢€2) 

ap24ga VALUE "XX", 

ABBAS 

20046 LINK&aGE SECTION, 

o7o4a7 
L 60dd8 COPY "CUSTRC,.CPY", 
L 2ua49 
L 38852 
L 48251 @1 CUSTOMER@FILE*RECORD, 
L aaese Q3 CUST=CUST=NUMBER PIc X(6),. 
L 42u53 a3 CUST=CUSTOMER@NAME PIC x(38), 
L gaasa 3 CUST*ADDRESSeL INES} PIc X(32). 
L 922955 a3 CUSTADDRESS=LINE@=2? PIC x30), 
L e2056 @3 CUST*ADDRESS=LINE=3 PIc X(308), 
L 809857 @3 CUST*@ADDRESS#ZIP=CODE PIC x(5). 
L geess a3 CUST=PHONE, 
L 82059 as CUST=PHONE=AREA@CODE PIc x(3), 
L 36962 as CUS TePHONE EXCHANGE PIC x(3), 
L 94961 25 CUST@PHONE@LAST@=4 PIC 9(a), 
L ed6e2 a3 CUSTePHONE@NUMBER 
L @Q@a63 REDEFINES CUST=PHONE PIC 9(18).6 
L 82064 3 CUST@ATTENTIONeLINE PIc x28), 
L ages a3 CUST@CREDITeLIMIT PIc 9618) 499, 
L Janes 03 CUST*HEADEReDATA REDEFINES CUST@CREDIT@=LIMIT, 
L 2ee67 a5 FILLER PIc X(6), 
L 4@¥68 @5 NEXT*ACCTeNUMBER PIc 906), 
L 22969 @3 CUST*OQNESAMT 
L #9874 Fic S(iSVSS, 
L 43071 83 CUST*B0UGHT 
L a2p7e PIC 9(18)V99, 
i #4e73 63 CUST@NEXT@OROER@SEGQUENCE Pic 9(4), 
L 49074 a3 CUSTeNEXT@PAYMENT@SEQUENCE PIC 9fa), 
L ana7s 

49076 PROCEDURE DIVISION USING 

AO277 CUSTOMER=FILE=RECORD, 

a2a7a 

@0279 DECLARATIVES, 

03080 

Aewal REPORT*ERROR SECTION, 


G-16 


USE 


DISPLAY 


IF 
OPEN 
MOVE 
MOVE 


WRITE 


MOVE 
WRITE 


MOVE 


WRITE 


COBOL 


MOVE 


WRITE 


MOVE 
MOVE 
WRITE 


MOVE 
WRITE 


EXIT 


4.94 


ai 


B1 


ee 
@2 
v2 
a2 
G2 


G2 
Be 


a2 


a2 


2 
a2 


b2 
ee 


62 


2 
2 


2 


SOURCE PROGRAM LISTINGS 


B20206 


@28aC6 


280006 
@0dbee 
802832 
ee2gue 


888252 


@20G76 


@48186 


890132 


@68142 


SRCsDOCATS. 


@08166 


@@8176 


a0a222 
200232 


Bedede 


880266 


@30276 


828322 


30882 
80883 


bee84 
88085 
88086 
80087 
08088 
@8Q89 
B609D 
8Ga91 
0892 
88093 
20094 
86095 


20096 
28097 


92098 


e289 
83198 


6@121 


CBL34 


22192 
@9123 


82104 


88105 
98186 


891937 
43188 


88149 
9211@ 


QOL 


Q8112 
BO113 


@6114 


USE AFTER STANDARD ERROR PROCEDURE ON LASEL=REPORT, 
SBEGIN, 


DISPLAY "IeO ERROR ON LASEL=REPORT, CODE (” 
LABEL*REPORT@STATUS 
LP har 


END DECLARATIVES, 


MAINLINE SECTION, 
SBEGIN, 


IF LABEL@REPORT@STATUS & "XX" 

OPEN OUTPUT LABEL@REPORT, 
MOVE SPACES TO LABEL@REPORT*RECORD, 
MOVE CUSTeCUST*NUMBER TO LR#ACCOUNT, 


WRITE LABEL*REPORT*RECORD 
AFTER ADVANCING 1 LINE, 


MOVE CUST@CUSTOMEReNAME TO LABEL*REPORT@=RECORD, 


WRITE LABELSREPORTH=RECORD 
AFTER ADVANCING 2 LINES, 


MOVE CUST@ADORESS@LINE*1 TO LABEL*®REPORT@=RECORD, 


OS-OCTe78 g6848:235 PAGE 323 


WRITE LABEL=REPORTeRECORD 
AFTER ADVANCING 1 LINE, 


MOVE CUST*ADDRESS=LINE@2 TO LABEL=REPORT@RECORD, 


WRITE LABELeREPORT@RECORD 
AFTER ADVANCING 1 LINE, 


MOVE CUST@ADDRESS@LINE#3 TO LABEL@REPORT@RECORD, 
MOVE CUST#ADDRESSeZIPeCODE TO LReZIP, 


WRITE LABEL*REPORT@RECORD 
AFTER ADVANCING 1 LINE, 


MOVE SPACES TO LABEL#=REPORT®RECORD, 


WRITE LABEL*REPORT*RECORD 
AFTER ADVANCING 2 LINES, 


EXIT PROGRAM, 


G-17 


SOURCE PROGRAM LISTINGS 


COBOL 4,90 SRC:DOCATS,CALS4 BS9O0CT#78 86:48:23 PAGE Bas 


FILEeTO#LUN ASSIGNMENT TABLE 


NAME SOURCE RELATIVE 
LINE LUN 
LABEL®REPORT CER S| UOO2Z1. 
DATA MAP 
LEVEL NAME SOURCE ODIV DIR USAGE CLASS OCC LEN 
LINE LOCN Loc 
FD LABEL*REPORT O3¥31 BAdD4G 
G1 LABELeREPORT=RECORD 2033 @22347@ G@B9G4N DISP AN 8 baad 
o1 LeR=DETAIL BA034 QAdW47A akewnke DISP AN BO 8240 
93 LReACCOUNT 20936 486532 222206 DISP AN 98 8886 
@i LeR=DETAIL@2 90037 BBCU7G waekee DISP AN @@ 0837 
23° LReZIP @2039 980530 @80014 DISP AN aa 8085 
@1 LABEL@REPORT#STATUS 83043 920542 @Yvd22 DISP AN @2 8882 
L @1i CUSTOMER@FILE*RECORD 00051 G@A@UGGZ wxkeeek DISP AN @2 8205 
L 93 CUST#CUST=NUMSER Beas2 gave28 @avasea DISP AN 88 2006 
L 83 CUSTeCUSTOMER@NAME 02853 BAGV26 BSvdd6 DISP AN 80 9830 
L A3.  CUST=ADDRESS@LINE@] 99054 BadQde Beeui4d DISP AN 86 9030 
L 83 CUST#ADDRESSeLINES2 @9a55 BB¥1G2 QBYAa22 DISP AN a@ o93a 
L 3 CUSTeADDRESSeLINES§ 99456 2240149 900430 DISP AN eg aa3a 
L @3 CUSTeADDRESSeZIPeCODE @AB57 284176 AdAV3e DISP AN @@ 8805 
L a3 CUST=PHONE 26858 BWad2e3 xxxweex DISP AN AB 88128 
L 8S CUST*PHONE*ARE A@CODE 22089 @28203 xeexxxx DISP AN 08 0883 
L @S CUST=PHONESEXCHANGE QYBCOD OLU2R6 xxeuae DISP AN 88 aoa3 
L BS CUSTePHONESLAST a4 @@061 O90211 weeuxx DISP NUM @@ BBe4 
L 63 CUST@PHONE*NUMBER 82862 BEG2G35 xekxee DISP NUM 22 8018 
L 23° CUSTeATTENTIONSLINE OG264 A@2U215 xeeexe DISP AN aa e820 
L 43) CUST=CREDIT=LIMIT 8286S BB0241 awkeee DISP NUM 88 @8i12 
L 23 CUSTeHEADER@ DATA BdV65 880241 sewkwe DISP AN @@ aaie 
L @5 NEXTACCTeNUNGER BA068 VAIZGT xaexaae DISP NUM 88 0886 
L 03 CUSTsOMESAMT A469 282255 xawanee DISP NUN 83 8012 
L 93 CUST=8O0UGHT BOQ71 AVs!Y]71 xaeeee DISP NUM a2 @812 
L 23 CUSTeNEXTeORDEReSEQUENCE 20073 O80305 awxeaee DISP NUM Qa @004 
L 3 CUST=NEXT@PAYMENT@SEQUENCE B8O74 BBA3i, xaxeek DISP NUM aa 8804 


PROCEDURE NAME MAP 


NAME SOURCE PSECT OFFSET SEG SECT PARA 
LINE 

REPORTSERRGR @eesi Sous. eeeves 22 & 

SBEGIN 28063 S$00001 wveueuss 48 P 

MAINLINE 8339¢@ S$D0e¥2 BABABE 42a 8 

SBEGIN @a291 S$00ve2 BeBa06 Be P 


SEGMENTATION mar 


SECTION NAME SEGMENT NO, NAME SIZE 
REPORT@ERROR oa 300081 20054 Bavee 
MAINLINE i) $0082 @8G346 Bits 


Q 
I 
— 
a 


SOURCE PROGRAM LISTINGS 


COMPILER GENERATED PSECTS 
NAME SIZE 


SDOENT 888236 eaets 
$00023 deea54 ave2e 


REFERENCED OTS ROUTINES 


$XOPEN EXWRIT SXEDIS $XG0 SXENDP SXEXIT $XSUBK SXINIT 
SCSTNE SMJUSL SMCFST SMGLA 


DATA PSECT MAP 


NAME SIZE 

SOCDAT Gba5a4 aei76 
soocoo eBa23e aaaie 
SDOPOT ea6e14 Bab 
SDCARS Ba2ee4 23gi8 
SDOWRK B4ue1z26 83035 
SDOLIT 290064 @8226 
SDOLTD @A2I36 @aais 
SDOLST vbeage G4081 
SOOPFM 626214 a0a7e 
SDOSDT a280R8 BAgGBB 
SDOADT BADEAB agaae 
$DOUSE 826338 aable 
SCBIOT aaei134 22846 


SCEF Aj b4012e b2e4s 
SCBXA1 BAavege gue2a 
$DO010B8 821082 Be256 
SCBIF1 oe@aaer 08024 
SCBIR1 BBAn48 @2216 
SCBKDI e2aeoe 2G020 
$CBB01 ogeeed aegiea 


$CBKB1 030009 auged 
SCBFD! 680002 Qdee1 
$CBSAT daev02 a@eel 


EXTERNAL SUBPROGRAM REFERENCES 


NO EXTERNAL SUBPROGRAM REFERENCES 


NO ERRORS 


COMPILER GENERATED OOL FILE 


;COBOL STANDARD ODL FILE GENERATED ON? @5*0CT=78 46:48:23 
;COBOBJ=SDOCATS. OBJ 
sCOBKER=D0 
pRMSREQ=CIOGIS 
sNAME 008@25,GBL 
sPSECT $00003,GBL+1/ Rw» CON 
DOw25S: .FCTR *00Su25~$0G60u3 
DOOVRE: ,FCTR poe2ss 


APPENDIX H 


DIAGNOSTIC ERROR MESSAGES 


This Appendix contains a numerical listing of the diagnostic messages 
generated by the compiler. Following the text of most messages are 
explanations of the diagnostics, including descriptions of the 
compiler's recovery actions. 


981 CONTINU 


ty 
tg 

= 
QO 

c 
4 
| 

in} 
to 
to 
Y 
2 
Ww 
ep) 
| 
HP 
| 
td 

iq 
td 
va 
ta | 


- IGNORED. 


A blank line has a continue indicator. 
The continue indicator is ignored. 


G2 QUOTE OR CONTINUE PUNCH MISSING. QUOTE ASSUMED. 


A non-numeric literal has no quote and 
the following line has no continuation 
indicator. A terminal quote is assumed 
at the end of the line. 


$83 VIOLATION OF AREA A. ASSUMED CORRECT. 


The first non-blank character on a 
continued line occurs in Area A. The 
error is ignored. 


g@4 LINE LENGTH EXCEEDS INPUT BUFFER. TRUNCATED. 


Continuation lines cause a COBOL word to 
exceed the capacity of the input buffer. 
The word is truncated on the right; the 
number of characters retained depends on 
the type of word being processed. 


g@5 .IO0 CONTROL. WITHOUT .FILE CONTROL. IGNORED. 


An I-O-CONTROL paragraph appears when no 
FILE-CONTROL paragraph was present. The 
I-O-CONTROL paragraph is ignored. 


G6 .STRING. DATA ITEM MUST HAVE DISPLAY USAGE. 


A data item in a STRING statement is not 
defined with DISPLAY usage. Fatal. 


97 NAME EXCEEDS 3@ CHARACTERS. TRUNCATED TO 39. 


A character-string that appears to be a 
name exceeds 3f@ characters in length. 
The string is truncated on the right to 
38 characters. 


G19 


fll 


$12 


G13 


g14 


g15 


#16 


g17 


$29 


G21 


DIAGNOSTIC ERROR MESSAGES 


NUMERIC LITERAL OVER 18 DIGITS. TRUNCATED TO 18. 


A numeric literal exceeds 18 digits in 
length. The literal is truncated on the 
right, with any necessary adjustm:nt to 
scaling. The sign is retained. 


NUMERIC LITERAL HAS MULTIPLE DECIMAL POINTS. 


A numeric literal has more than one 
decimal point. 


PICTURE CLAUSE ILLEGAL ON GROUP LEVEL. IGNORED. 


A group level item has a PICTURE clause. 
The clause is ignored. 


-SELECT. NOT FOUND. SENTENCE IGNORED. 


A FILE-CONTROL statement should begin 
with the word SELECT, but does not. All 
words up to the next period are ignored. 


JUST.SYNC.BLANK CLAUSES WRONG AT GROUP. IGNORED. 


A group level item may not contain 
JUSTIFIED, SYNCHRONIZED, or BLANK WHEN 
ZERO clauses. The clause is ignored. 


FILENAME MISSING OR INVALID. SELECT IGNORED. 


A SELECT statement either contains no 
user name or the the user name is 
invalid. The SELECT statement is 
ignored. 


USAGE CONFLICTS WITH GROUP USAGE. USES GROUP. 


The usage specified for this item 
differs from the usage stated at a 
higher group level. The group level 
usage is used. 


ILLEGAL NUMERIC DATANAME IN .STRING. 


A numeric data item in a STRING 
statement has an illegal description. 
Fatal. 


-ALL. ILLEGAL IN CONTEXT OF .STRING. STATEMENT. 


An ALL literal has been used in a STRING 
Statement. Fatal. 


SYNTAX ERROR OR NO TERMINATOR. CLAUSES SKIPPED. 


A SELECT statement is missing its 
terminating period, or an error causes 
the statement to be processed before all 
clauses were found. The SELECT 
statement is ignored. 


G22 


$23 


G24 


$25 


$26 


G27 


939 


G31 


$32 


$33 


DIAGNOSTIC ERROR MESSAGES 


NUMERIC LITERAL ILLEGAL IN THIS STATEMENT. 


A STRING, UNSTRING, or INSPECT statement 
contains a numeric literal. Fatal. 


SENDING LIST OMITTED IN .STRING. STATEMENT. 


A STRING statement contains no_ sending 
fields before a DELIMITED BY phrase. 
Fatal. 


MORE THAN ONE FILENAME IN .ASSIGN. 


The non-numeric literal of an ASSIGN 
clause contains more than one file 
specification. Only the first 
specification is used. 


ILLEGAL DATANAME FOLLOWS .INTO. IN .STRING. 


The 


r 
statem 


eceiving field fe) 
ent is invalid. Fat 


f a STRING 
ale 


SUBSCRIPTING DEPTH EXCEEDS 3. OVER 3 IGNORED. 


The OCCURS clause is nested more than 
three deep. The clause is ignored. 


VALUE ILLEGAL IN OCCURS ITEM. IGNORED. 


A VALUE clause appears in an item with 
an OCCURS clause or in an item 
subordinate to an OCCURS clause. The 
VALUE clause is ignored. 


VALUE ILLEGAL IN REDEFINES ITEM. IGNORED. 


A VALUE clause appears in an item that 
either contains a REDEFINES clause or is 
subordinate to an item with a REDEFINES 
clause. 


NO TERMINATOR FOR .IO CONTROL. PARAGRAPH. 


The I-O-CONTROL paragraph is not 
terminated by a period. The terminator 
is assumed present. 


-MAP. NO LONGER APPLICABLE. IGNORED. 


An APPLY clause with the MAP option is 
not applicable for this version and 
future versions of the compiler. The 
APPLY clause is ignored. 


AN IO CONTROL CLAUSE WITHOUT FILES. 
A file-name is missing in a clause of 


the I-O-CONTROL paragraph. The clause 
is ignored. 


$34 


$35 


$36 


$37 


G49 


g4i 


$42 


$43 


p44 


G45 


DIAGNOSTIC ERROR MESSAGES 


SYNTAX ERROR IN .APPLY. 


An APPLY clause has illegal syntax. The 
clause is ignored. 


INVALID ACCESS MODE. TREAT AS SEQUENTIAL. 


The SELECT statement contains an invalid 
ACCESS mode. SEQUENTIAL ACCESS mode is 
assumed. 


INVALID FILE ORGANIZATION. TREAT AS SEQUENTIAL. 


The SELECT statement contains an invalid 
ORGANIZATION specification. SEQUENTIAL 
organization is assumed. 


NO SELECT STATEMENTS. 


A FILE-CONTROL paragraph either contains 
no SELECT statements or none of those 
present is valid. The FILE-CONTROL 
paragraph is ignored. 


-ASSIGN. OMITTED FROM SELECT. SELECT IGNORED 


A SELECT statement contains no ASSIGN 
clause. The SELECT statement is 
ignored. 


DECIMAL PLACES TRUNCATED. 


Decimal places have been truncated from 
a numeric literal during conversion for 
use as an integer. The integer 
positions are used. 


INTEGER EXPECTED, ZERO ASSUMED. 


An integer literal was expected, but 
fractional positions were found. The 
literal is ignored and a value of zero 
is assumed. 


INTEGER VALUE TOO BIG. LARGEST VALUE USED. 


A numeric literal is too big for 
conversion as an integer in the given 
context. A value of 32,767 is used. 


ERROR IN DATA RECORDS CLAUSE. CLAUSE SKIPPED. 
The word DATA is not followed by RECORD 
or RECORDS in the DATA RECORDS clause. 
The DATA RECORDS clause is ignored. 
ERROR IN LABEL RECORDS CLAUSE. CLAUSE SKIPPED. 
The word LABEL is not followed by RECORD 


or RECORDS in the LABEL RECORDS clause. 
The LABEL RECORDS clause is ignored. 


G46 


G47 


G59 


G51 


G52 


G53 


g54 


g55 


$56 


DIAGNOSTIC ERROR MESSAGES 


NO INTEGER IN BLOCK CLAUSE. CLAUSE SKIPPED. 


The BLOCK clause does not contain a 
numeric literal. The BLOCK clause is 
ignored. 


BAD VALUE IN BLOCK CLAUSE. CLAUSE SKIPPED. 


The numeric literal in the BLOCK clause 
causes an illegal block size. The block 
size in bytes must be greater than @ and 
less than 32768. The BLOCK clause is 
ignored. 


NO INTEGER IN RECORD CLAUSE. CLAUSE SKIPPED. 


The RECORD CONTAINS clause does not 
contain a numeric literal. The RECORD 
CONTAINS clause is ignored. 


INVALID VALUE IN RECORD CLAUSE. CLAUSE SKIPPED. 

The numeric literal in the RECORD 
CONTAINS clause is not greater’ than 
zero. The RECORD CONTAINS clause is 
ignored. 


INVALID FILENAME. FD SKIPPED. 


The word following FD is not valid as a 


file-name. The FD entry is ignored. 
FD TERMINATOR MISSING. ASSUMED PRESENT. 


The file description entry contains no 
period terminator. The error is 
ignored. 


KEY WORD EXPECTED. REMAINING CLAUSES SKIPPED. 


A keyword that begins a clause, such as 
BLOCK, LABEL, DATA, etc., is missing. 
The remainder of the FD entry is 
ignored. 


NO LABEL CLAUSE IN FD. .STANDARD. ASSUMED. 


The FD entry contains no LABEL RECORD 
clause. LABEL RECORD IS STANDARD is 
assumed. 


NO SELECT. FILE DELETED. 


The FD entry's file-name has no 
corresponding SELECT statement. The FD 
entry. is ignored. All references to the 
file-name will be diagnosed as 
undefined. 


O57 


G66 


$61 


$62 


$63 


g64 


p65 


$66 


67 


DIAGNOSTIC ERROR MESSAGES 


ALLOCATED SPACE EXCEEDS LARGEST RECORD. 


The maximum record size specified by the 
‘RECORD CONTAINS clause exceeds the space 
required for any #1 entry under the same 
file. The value specified by the RECORD 
CONTAINS clause is used. 


RECORD AREA EXTENDED TO CONTAIN LARGEST RECORD. 


The space required by the largest 1 
record under a file description exceeds 
the space required by the RECORD 
CONTAINS clause in the FD entry. The 
value derived from the G1 record 
description is used. 


NO RECORD AREA. FILE DELETED. 
No record area is allocated for a file 
description. The file description is 


ignored. All references to the file 
will be diagnosed as undefined. 


ILLEGAL DATANAME FOLLOWS .WITH POINTER. PHRASE. 
The data item used as a pointer in a 
STRING or UNSTRING statement is illegal. 
Fatal. 

ILLEGAL SYNTAX IN .STRING. STATEMENT. 


A STRING statement contains illegal 
syntax. Fatal. 


77 ILLEGAL IN FILESECTION. CHANGED TO @1. 


A 77 level item description has been 
found in the FILE SECTION. The 77 level 
is treated as an §1 level. 


ILLEGAL WORD FOLLOWS .DELIMITED BY. PHRASE. 
A data-name or literal is expected 
following a DELIMITED BY phrase ina 
STRING or UNSTRING statement. Fatal. 
ILLEGAL USE OF .ALL.. IGNORED. 
In the VALUE clause, an ALL numeric 
literal is detected. ALL is ignored by 
the compiler. 


CONDITION NAME MISSING OR INVALID. 88 IGNORED. 
The condition-name in an 88 level entry 


is either missing or invalid. The 
entire entry is ignored. 


B79 
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G72 
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G75 


G76 


977 


166 


DIAGNOSTIC ERROR MESSAGES 


TWO INDEXED KEYS START AT SAME OFFSET IN RECORD. 


The leftmost character position of the 
RECORD KEY or ALTERNATE RECORD KEY 
data-name corresponds. to the leftmost 
character position of some other RECORD 
KEY or ALTERNATE RECORD KEY data-name. 
The clause is ignored. 


-REDEFINES. ON §1 LEVEL IN FILE SECTION INVALID. 


The REDEFINES clause is present on the 
Gl level in the FILE SECTION, where 
redefinition is implicit. REDEFINES 
clause is ignored. 


PICTURE IGNORED FOR INDEX ITEM. 
An item defined as USAGE INDEX has a 
PICTURE clause. The PICTURE clause is 
ignored. 


NONNUMERIC PIC ON COMP ITEM. TREATED AS DISPLAY. 


An item defined with non-DISPLAY usage 
has a picture-st:ring with non-numeric 


characters. The stated usage is 
ignored. The item is treated as USAGE 
DISPLAY. 


SUBSCRIPT OUT OF RANGE. ASSUME 1. 


A literal subscript is either less than 
1 or greater than the maximum allowable 
value. A value of 1 is used. 


-STATUS. OMITTED FROM .FILE STATUS.. ASSUMED. 


The FILE STATUS clause has incorrect 
syntax. The error is ignored. 


SOME FILES WITHOUT POSIT. NO. IN MUL. FILE TAPE. 


A MULTIPLE FILE TAPE clause contains 
file-names with POSITION clauses. Not 
all the file-names contain POSITION 
clauses. The error is ignored. File 
searching during OPEN will find the 
file. 


-MULTIPLE FILE TAPE. SYNTAX ERROR. 


A MULTIPLE FILE TAPE clause contains a 
syntax error. The clause is ignored. 


OPERAND CLASSES IN CONFLICT. 


One or more operands in a statement have 
an invalid class. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


POSSIBLE RECEIVING FIELD TRUNCATION. 


A MOVE statement results in right-hand 
truncation of the receiving field value. 
This is not an error and is ignored. 


TOO FEW SOURCE FIELDS FOR ADD .GIVING.. 


At least two valid source operands must 
appear in an ADD...GIVING statement. 
Fatal. 

~EXIT. WAS NOT THE ONLY VERB IN PARAGRAPH. 


An EXIT statement is not’ the only 
Statement in a paragraph. The EXIT 
statement is ignored. 

SENDING ITEM INVALID OR OMITTED. 


A MOVE statement contains an invalid or 
missing sending operand. Fatal. 


SENDING ITEM NOT FOLLOWED BY .TO.. 


A MOVE statement does not have the 
keyword TO following the sending 
operand. Fatal. 

RECEIVING ITEM INVALID OR OMITTED. 


A MOVE statement has no valid receiving 
operand. Fatal. 


INVALID CLASS FOR DESTINATION FIELD. 


The receiving operand of an ADD or 
SUBTRACT statement is not. numeric or 
numeric edited. Fatal. 


RELATIVE OR RECORD KEY OR STATUS NAME INVALID. 
The name referenced in a RELATIVE KEY, 
RECORD KEY, ALTERNATE RECORD KEY or FILE 
STATUS clause is invalid. The clause is 
ignored. 

-STOP. SYNTAX ERROR. 


The STOP statement is not followed by a 


literal or the word RUN. Fatal. 
eSI1ZE ERROR. STATEMENT INCORRECT. 


The word ERROR is not found in the ON 
SIZE,clause. Fatal. 


»~PROCEDURE DIVISION. OMITTED. 


The source program does not contain a 
PROCEDURE DIVISION. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


INTERMEDIATE RESULT TOO LARGE. HIGH ORDER TRUNC. 


An arithmetic statement calls for an 
intermediate result in excess of 18 
digits. The intermediate result is 
truncated on the left to 18 digits, with 
a possible loss of high-order, non-zero 
digits at execution time. 


INTERMEDIATE RESULT TOO LARGE. LOW ORDER TRUNC. 


An arithmetic expression calls for an 
intermediate result in excess of 18 
digits. The intermediate result is 
truncated on the right to 18 digits, 
with a possible loss of low-order, 
non-zero digits at execution time. 


-DIVISION. OMITTED AFTER .PROCEDURE.. 
The word DIVISION is missing in the 
PROCEDURE DIVISION header. The error is 
ignored. 


TERMINATOR MISSING AFTER DIVISION HEADER. 


The period terminator is missing from a 
division header. The error is ignored. 


LITERAL INCOMPATIBLE WITH ATTEMPTED USAGE. 


Conversion of a literal from one form to 
another has failed. Fatal. 


DATANAME MUST FOLLOW .INTO. IN THIS STATEMENT. 
A valid data-name is not present 
following INTO in a STRING or UNSTRING 
Statement. Fatal. 

NUMERIC SUBJECT OR OBJECT MUST BE INTEGER. 
A numeric, non-integer subject or object 
is invalid in the context of this 
relation condition. Fatal. 


OPERANDS CONFLICT IN .SET...TO. STATEMENT. 


A SET...TO statement references invalid 
operands. Fatal. 


OPERANDS CONFLICT IN .SET ...BY. STATEMENT. 


A SET...BY statement references invalid 
operands. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


ILLEGAL FILENAME LITERAL OR FILENAME DATANAME. 


An ASSIGN statement or a VALUE OF ID 
statement contains an invalid file 
specification or data-name. The 
statement is ignored. 


INVALID SUBJECT OF SIGN CONDITION. 


The subject of a sign condition is not a 
valid arithmetic expression. Fatal. 


ITEM IN TABLE MAY NOT BE USED AS A SUBSCRIPT. 


A data item used as a subscript is 
itself a table element. Fatal. 


~POINTER. MUST FOLLOW .WITH. IN THIS STATEMENT. 


A STRING or UNSTRING statement has an 
invalid WITH POINTER phrase. Fatal. 


RELATIVE KEY INVALID FOR THIS FILE. IGNORED. 


A RELATIVE KEY clause has been applied 
to a file that does not have RELATIVE 
Organization. The RELATIVE KEY clause 
is ignored. 


SUBJECT OR OBJECT OMITTED IN RELATION CONDITION. 


The subject or object is omitted in a 
COBOL relation condition. Fatal. 


UNIDENTIFIABLE WORD FOUND IN SUBSCRIPT. 


A subscript list contains a word that is 
neither a data-name nor a numeric 
literal. The remainder of the list or 
sentence is ignored. Fatal. 


INVALID SUBJECT OR OBJECT IN RELATION CONDITION. 


The subject or object of a relation 
condition is an invalid operand. Fatal. 


SUBSCRIPTS OMITTED. ASSUME VALUE OF 1. 


A reference to a table item contains no 
subscript list. Literal subscripts of 1 
are supplied as defauits. 


RELATIVE INDEX LITERAL OUT OF RANGE. INDEX USED. 
The literal value of a relative index 
causes an out-of-range reference to the 


table. The literal value is ignored, 
and only the index-name is used. 
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DIAGNOSTIC ERROR MESSAGES 


SUBSCRIPTS GIVEN WHERE NOT REQUIRED. IGNORED. 


A reference is made to a non-table item, 
and a subscript list follows’ the 
reference. The subscript list is 
ignored. 


TOO FEW SUBSCRIPTS GIVEN. ASSUME 1 FOR REST. 


A reference to a table item contains a 
subscript list with too few subscripts. 
Default literal subscripts of 1 are 
supplied for missing subscripts. 


TOO MANY SUBSCRIPTS GIVEN. IGNORE EXCESS. 


A reference to a table item contains too 
Many subscripts in the subscript list. 
Extra subscripts are ignored. 


SUBJECT AND OBJECT USAGE MUST MATCH. 


A relation condition between non-numeric 
operands requires the same usage for 
both operands. Fatal. 


ARITHMETIC EXPRESSION REQUIRED IN THIS CONTEXT. 


An arithmetic expression is required in 
the context of the COBOL statement being 
compiled. The compiler has failed to 
recognize the arithmetic expression in 
this context. Fatal. 


CONDITION EXPRESSION REQUIRED IN THIS CONTEXT. 


A condition expression is required in 
the context of the COBOL statement being 
compiled. The compiler has failed to 
recognize the condition expression in 
this context. Fatal. 


ILLEGAL OPERAND FOUND IN COBOL EXPRESSION. 


An invalid data-name or literal has been 
found in the COBOL statement being 
compiled. The class or USAGE of the 
data item may be invalid here asa 
reference in an expression. Fatal. 


OPERATOR IS MISSING IN COBOL EXPRESSION. 


An operator is omitted in the 
specification of this COBOL expression. 
The compiler cannot recognize this 
expression as a syntactically valid 
COBOL expression. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


ABSOLUTE VALUE STORED. 


A negative value has been supplied for 
an unsigned numeric item. The absolute 
value of the numeric literal is stored 
in the item. 


ILLEGAL WORD FOUND AFTER .NOT. IN EXPRESSION. 


mh 
ail 
e 


€ compiler has detected an illegal 
xpression operator following a NOT 
keyword in the COBOL expression being 


compiled. Fatal. 
VERB FOUND IN AREA A. ALLOWED. 


A statement begins in Area A. The error 
is ignored. 


EXPECTED .RELATIVE KEY. DATANAME NOT DEFINED. 


The data-name given in a RELATIVE KEY 
clause has not been defined in the Data 
Division. 


-LINAGE. CLAUSE DATAITEM IS TOO LONG. 


A data item named in a LINAGE clause is 
declared in the Data Division with more 
than four decimal integer positions of 
precision. 


PROCEDURE NAME DUPLICATES DATA NAME. ALLOWED. 


A procedure name is identical to a 
data-name. The error is ignored, since 
there can be no ambiguity in legal 
references. 


STATEMENTS FOLLOWING .GO. CAN NEVER BE EXECUTED. 


A statement follows an unconditional GO 
Statement. The statements following the 
GO are compiled, but cannot be executed. 


NONSEQUENTIAL FILE MAY NOT BE OPTIONAL. 


The SELECT statement may specify 
OPTIONAL only on files with sequential 
organization. The word OPTIONAL is 
ignored. 


A file is given conflicting clause 
specifications in the I-O-CONTROL 
paragraph of the INPUT-OUTPUT SECTION. 
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DIAGNOSTIC ERROR MESSAGES 


FILE REQUIRES REL. KEY. TREATED AS SEQ. ACCESS. 


A file with relative organization and 
random or dynamic access has no RELATIVE 
KEY clause. The access mode is changed 
to SEQUENTIAL. 


INVALID INDEX DATAITEM USE IN RELATIONAL. 


The compiler detects the invalid use of 
an index data item reference as the 
subject or object of a relation 
condition. Fatal. 


UNKNOWN WORD. SCAN TO NEXT CLAUSE. 


An unknown word is encountered when a 
clause keyword is expected. All words 
are ignored up to the next valid clause. 


CLAUSE DUPLICATED. SECOND OCCURRENCE USED. 


A SELECT statement contains two 
occurrences of the same clause. The 
second occurrence is used. 


NO FD FOR THIS SELECT. 


The file-name supplied in a SELECT 
statement is not further described in an 
FD in the Data Division. The SELECT 
statement is ignored, causing the 
file-name to become undefined. 


DIFFERENT SAME REC. AREAS FOR SAME AREA. 


The compiler detects a conflict between 
the SAME RECORD AREA clause and the SAME 
AREA clause. 


-READ. WITHOUT .INVALID KEY. .AT END. OR .USE. 


A READ statement contains no conditional 
clauses, and the file being read has no 
USE procedure applied to it. Fatal. 


IO CONTROL CLAUSE HAS FILE WITH NO .SE;ECT. 


An I-O-CONTROL clause references a 
file-name that was not named in a SELECT 
statement. The file-name is ignored in 
the I-O-CONTROL statement. 


INTEGER OMITTED IN .RESERVE.. DEFAULT ASSUMED. 


A RESERVE clause fails to specify the 
number of buffer areas to reserve. The 
clause is ignored, and a default of one 
area for SEQUENTIAL and RELATIVE, or two 
areas for INDEXED, is supplied. 
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DIAGNOSTIC ERROR MESSAGES 


171 INVALID SUBJECT OF CLASS CONDITION. 


The subject of a class condition is not 
a data item with an acceptable class. 
Fatal. 


172 VALUE EXCEEDS FIELD CAPACITY. TRUNCATED. 


A numeric literal supplied by a VALUE 
clause exceeds the length of the field. 


The value is right truncated and stored 
in the field. 


173 NO DATA DIVISION STATEMENTS PROCESSED. 


The Data Division contains no _ valid 
entries. This is an observation only. 


174 INVALID GRP LEV NUM. REST OF RECORD IGNORED. 


A level-number is encountered that 
terminates a previous group item, but 
does not match any previous group item's 
level-number. All data entries are 
skipped until the next #1 level, level 
indicator or header. 


175 INVALID PROCEDURE NAME DEFINITION IN AREA A. 


The compiler detects source text in Area 
A of the Procedure Division that does 
not conform to the rules for the 
definition of a legitimate paragraph or 
section name. Source text found in Area 
A of the Procedure Division is 
interpreted by the compiler as a _ user 
attempt to define a new paragraph or 
section name. The compiler supplies a 
system-defined procedure name and 
proceeds with the processing of the 
source line text containing the invalid 


Area A text. The system-defined 
procedure name is transparent and, thus, 
inaccessible to the user. 


176 MISSING QUOTE ON CONTINUE LINE. QUOTE ASSUMED. 


A non-numeric literal is continued, but 
the first non-space character is not a 
quote. The error is ignored by assuming 
a quote in front of the first non-space 
character. 


177 COMPARISON OF LITERALS IS NOT PERMITTED. 


A relation condition has a literal as 
both subject and object. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


COPY IGNORED WITHIN LIBRARY TEXT. 
A COPY statement is encountered within 


library text. The COPY statement is 
ignored. 


INVALID FILENAME ON COPY. COPY IGNORED. 
A COPY statement supplies a file 
specification that is invalid. The COPY 
statement is ignored. 

COPY FILENAME NOT FOUND. 
A COPY statement supplies a valid file 
specification, but the file cannot be 
found on the specified device. The COPY 
statement is ignored. 


PERIOD OMITTED AFTER .DECLARATIVES.. 


llowed by 


The word DECLARATIVES is not fo 
a period. The error is ignored 
»-DECLARATIVES. OMITTED FROM .END. STATEMENT. 
The word END is not followed by 
DECLARATIVES. END DECLARATIVES is 
assumed. 
PERIOD OMITTED AFTER .END DECLARATIVES.. 
The words END DECLARATIVES are not 
followed by a period. The error is 
ignored, 
SOURCE PROGRAM ENDS IN DECLARATIVES. 


The end of the source program occurs in 
the Declaratives area. Fatal. 


DATANAME MUST FOLLOW .WITH POINTER. PHRASE. 


A STRING or UNSTRING statement contains 
an invalid WITH POINTER phrase. Fatal. 


-OVERFLOW. MUST FOLLOW .ON. IN THIS STATEMENT. 


A STRING or UNSTRING statement contains 
an invalid ON OVERFLOW phrase. Fatal. 


ILLEGAL SENDING FIELD DATANAME IN .UNSTRING. 


The sending field of an UNSTRING 
statement has an invalid class. Fatal. 


ILLEGAL SYNTAX IN .UNSTRING. STATEMENT. 


An UNSTRING statement has invalid 
syntax. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


MULTIPLE SIGN CLAUSES ON THIS ITEM. 


More than one SIGN clause appears in a 
data description. (SEPARATE must follow 
LEADING or TRAILING.) The second clause 
is used. 


ILLEGAL SYNTAX IN COBOL EXPRESSION. 


The compiler detects a syntax error of a 
general nature in the COBOL expression 
being compiled. Fatal. 


SIGN CLAUSE ON NONNUMERIC ITEM. 


A SIGN clause appears in a non-numeric 
data description. The SIGN clause is 
ignored. 

SIGN CLAUSE APPLIED TO NONDISPLAY ITEM. 


A SIGN clause appears in a numeric data 
description with usage other than 
DISPLAY. The SIGN clause is ignored. 


SIGN CLAUSE APPLIED TO UNSIGNED DATAITEM. 


A SIGN clause appears in a numeric data 
description that has no "S" in its 
PICTURE string. The SIGN clause is 
ignored. 

ILLEGAL DELIMITING DATA ITEM IN .UNSTRING. 


An UNSTRING statement references an 
invalid delimiter. Fatal. 


-ALL. FIGURATIVE CONSTANT ILLEGAL IN .UNSTRING. 


An UNSTRING statement contains an ALL 
literal reference. Fatal. 


ILLEGAL RECEIVING DATANAME IN .UNSTRING. 
An UNSTRING statement references a 
receiving data item that is invalid. 
Fatal. 


»-DELIMITED. CLAUSE REQUIRED IN THIS .UNSTRING. 


An UNSTRING Statement contains no 
DELIMITED BY clause. R 
DATANAME MUST FOLLOW .DELIMITER IN. PHRASE. 

An UNSTRING statement contains a 


DELIMITER IN phrase with an illegal 
reference. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


ILLEGAL DATANAME FOLLOWS .DELIMITER IN. PHRASE. 
An UNSTRING statement contains a 
DELIMITER IN phrase referencing a data 
item that is invalid. Fatal. 

DATANAME MUST FOLLOW .COUNT IN. PHRASE. 
An UNSTRING statement contains a COUNT 
IN phrase with an illegal reference. 
Fatal. 

ILLEGAL DATANAME FOLLOWS .COUNT IN. PHRASE. 
An UNSTRING statement contains a COUNT 
IN phrase that references an invalid 
data item. Fatal. 

DATANAME MUST FOLLOW .TALLYING IN. PHRASE. 


An UNSTRING statement contains a 
an 217 
a AL 


MATT WTA nheanan wrath 
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reference. Fatal. 

ILLEGAL DATANAME FOLLOWS .TALLYING IN. PHRASE. 
An UNSTRING statement contains a 
TALLYING phrase referencing a data item 
that is invalid. Fatal. 

DATANAME MUST FOLLOW .INSPECT. VERB. 


A valid data-name reference does not 
follow the INSPECT keyword. Fatal. 


ILLEGAL DATANAME FOLLOWS .INSPECT. VERB. 


An INSPECT statement references a data 
item that is invalid. Fatal. 


ILLEGAL DATANAME PRECEDES .FOR. IN .INSPECT. 
An INSPECT. ..TALLYING statement 
references a tally data item that is 
invalid. Fatal. 


-FOR. OMITTED IN .INSPECT. STATEMENT. 


An INSPECT...TALLYING statement has 
invalid syntax. Fatal. 


DATANAME MUST FOLLOW .TALLYING. PHRASE. 


An INSPECT...TALLYING statement does not 
reference a tally data-name. Fatal. 


ILLEGAL WORD FOLLOWS .FOR. IN .INSPECT. 


An INSPECT...TALLYING statement does not 
state a valid search condition. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


DATAITEM OMITTED AFTER .ALL. .LEADING. OR .FIRST. 


An INSPECT statement does not reference 
a valid search argument. Fatal. 


-ALL. FIGURATIVE CONSTANT ILLEGAL IN .INSPECT. 


An ALL literal appears in an INSPECT 
statement. Fatal. 


ILLEGAL DATANAME FOLLOWS .ALL. OR .LEADING. 


An INSPECT statement does not reference 
a valid search argument. Fatal. 


ILLEGAL DATANAME FOLLOWS .BEFORE. OR .AFTER. 
An INSPECT statement does not reference 
a valid delimiter in the BEFORE/AFTER 
Phrase. Fatal. 

ILLEGAL DATANAME FOLLOWS .BY. 


An INSPECT statement does not reference 
a valid replacement argument. Fatal. 


ILLEGAL DATANAME PRECEDES .BY. 
An INSPECT statement does not reference 
a legal data-name or literal preceding 
the BY phrase. Fatal. 

DATAITEM OMITTED IN .BEFORE. OR .AFTER. PHRASE. 
An INSPECT statement does not reference 
a legal data-name or literal after the 
BEFORE or AFTER phrase. Fatal. 

ILLEGAL SYNTAX IN .INSPECT. STATEMENT. 
Both the TALLYING and REPLACING keywords 
are missing in the INSPECT statement. 
Fatal. 

-BY. MUST FOLLOW .CHARACTERS. IN REPLACING LIST. 
The INSPECT...REPLACING statement must 
have CHARACTERS BY phrase completely 
Specified. Fatal. 

DATAITEM OMITTED AFTER .BY. IN .INSPECT. 
The INSPECT...REPLACING statement does 


not reference a legal data-name or 
literal after BY. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


DATAITEM FOLLOWING .BY. EXCEEDS 1 CHARACTER. 


In an INSPECT...REPLACING statement, 
when: 1) the CHARACTERS BY phrase is 
specified, or 2) a figurative constant 
preceding the BY keyword of the ALL, 
LEADING, or FIRST phrase is’ specified, 
the data-name or literal after the BY 
keyword must be defined as one character 
in length. Fatal. 


‘DATAITEMS BEFORE AND AFTER .BY. UNEQUAL IN SIZE. 


In an INSPECT...REPLACING statement, the 
data items before and after the BY 
keyword of the ALL, LEADING, or FIRST 
phrase must be equal in length. Fatal. 


»-BEFORE. OR .AFTER. OPERAND EXCEEDS 1 CHARACTER. 


In an INSPECT...REPLACING CHARACTERS BY 
statement, the data-name or literal 


following the BEFORE or AFTER keyword 
must be one character in length. Fatal. 


ILLEGAL WORD FOLLOWS .REPLACING. IN .INSPECT. 


A legal keyword was not recognized 
following REPLACING in the INSPECT 
Statement. Fatal. 


-BY. OMITTED AFTER REPLACING COMPARISON OPERAND. 


The keyword BY is omitted in the ALL, 
LEADING, Or FIRST phrase where it 
separates operands’ to be compared. 
Fatal. 


TOO MANY RIGHT PARENTHESES IN COBOL EXPRESSION. 


The compiler detects an excess of right 
parentheses in the COBOL expression 
being compiled. Parentheses must be 
specified in balanced pairs; that is, a 
left parenthesis must exist for each 
right parenthesis specified. Fatal. 


TOO MANY LEFT PARENTHESES IN COBOL EXPRESSION. 


The compiler detects an excess of left 
parentheses in the COBOL expression 
being compiled. Parentheses must be 
specified in balanced pairs; that is, a 
right parenthesis must exist for each 
left parenthesis specified. Fatal. 


MISSING OPERAND IN ARITHMETIC EXPRESSION. 


An operand is omitted in a COBOL 
arithmetic expression. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


ILLEGAL OPERAND IN ARITHMETIC EXPRESSION. 


The compiler detects an illegal operand 
in a COBOL arithmetic expression. The 
class or usage of the operand may be 
invalid in the context as a reference in 
an arithmetic expression. Fatal. 


The compiler detects a non-integer, 
numeric exponent in a COBOL arithmetic 
expression. The arithmetic expression 
is considered invalid. Fatal. 


SUBJECT OMITTED IN CLASS CONDITION. 


The compiler detects the omission of the 
Subject in a NUMERIC or ALPHABETIC class 
condition. Fatal. 


SUBJECT OMITTED IN SIGN CONDITION. 


The compiler detects the omission of the 
subject in a sign condition. Fatal. 


OPERAND MISSING IN COMPLEX CONDITION. 


The compiler detects the omission of an 
operand in an AND or OR _ complex 
condition. Fatal. 


INVALID OPERAND IN COMPLEX EXPRESSION. 


The compiler detects a complex condition 
operand that is not a simple condition, 
combined condition, or complex 
condition. Fatal. 


ILLEGAL SYNTAX IN NEGATED SIMPLE CONDITION. 


The compiler detects illegal syntax ina 
COBOL negated simple condition. Fatal. 


3 SF 


INVALID NEGATED SIMPLE CONDITION. 


The compiler detects the application of 
the NOT keyword to an invalid simple 
condition. Fatal. 


ILLEGAL SYNTAX IN .COMPUTE. STATEMENT. 


The compiler detects illegal syntax in a 
COMPUTE statement. The left side of the 
assignment symbol or the assignment 
symbal itself may have been 
omitted. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


-AT END. ILLEGAL FOR RANDOM .READ. 


The file is specified with either ACCESS 
RANDOM or ACCESS DYNAMIC without the 
word NEXT being included in the READ 
statement. The AT END clause is treated 
as an INVALID KEY clause. 


INVALID KEY ILLEGAL FOR SEQUENTIAL .READ. 


Either the file has ACCESS SEQUENTIAL or 
the READ statement contains the word 
NEXT. In either case, the INVALID KEY 
clause is illegal. It is treated as an 
AT END clause. 


INDEX DATA ITEM ILLEGAL AS INDEX ON TABLE. 


An index data item is used as an index 
for a table. The index data item 
reference is ignored. A literal 
subscript of 1 replaces the index data 
item reference. 


INDEX NAME NOT DEFINED FOR THIS TABLE. 


An index-name used in a subscript list 
either is not defined for this table or 
appears in the wrong logical position of 
the subscript list for this table. The 
index-name is ignored and a defauit 
value of 1 is assumed as the subscript. 


RELATIVE INDEX IS INVALID. 


The literal component of a relative 
index is zero or less in value, or is an 
invalid word. Relative indexing is 
ignored and only the index-name is used. 


PROGRAM NAME OMITTED AFTER .CALL. VERB. 


The program-name is omitted after the 
key word CALL. Fatal. 


LINAGE §@ OR LESS THAN FOOTING. 


The LINAGE clause must specify a page 
body of at least one line, and the page 
body size must be equal to or _ greater 
than the footing size specified in the 
FOOTING phrase. 


FILE CLOSED BUT NOT OPENED. 


A CLOSE statement was encountered for a 
file that is not opened in this program. 
Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


PRINT CONTROL ON NON SEQUENTIAL FILE. IGNORED. 


An APPLY PRINT-CONTROL clause references 
a file that does not have SEQUENTIAL 
organization. The file-name is ignored 
in the APPLY clause. 


DATANAME OMITTED IN .KEY IS. PHRASE. 


The KEY IS phrase of the START statement 
is not followed by a data-name. The 
prime RECORD KEY data-name is assumed 
present. 


SECTION OR PARAGRAPH NAME ‘MISSING. 


The Procedure Division does not start 
with a section or paragraph name, or a 
section header is not followed by a 
paragraph name. Fatal. 


«PROCEDURE. MISSING IN .USE. STATEMENT. ASSUMED. 


The keyword PROCEDURE is missing in the 
USE statement. It is assumed and 
processing is continued. 


-START. WITHOUT .INVALID KEY. OR .USE. 


The INVALID KEY option is missing from 
the START statement, or no USE procedure 
is declared for the referenced file. 
Fatal. 


-WRITE. WITHOUT .INVALID KEY. OR .USE. 


The INVALID KEY option is missing from 
the WRITE statement, or no USE procedure 
is declared for the referenced file. 
Fatal. 


DATA DIVISION MUCH TOO LARGE. 
Too much buffer space is being used for 
the files in this program. Too many 


files are declared to be OPEN 
Simultaneously. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


.REDEFINES. SPECIFIES INVALID REDEFINITION. 


The compiler detects the invalid 
application of REDEFINES to a data 
description entry that contributes new 
character positions between the data 
description entry containing the 
REDEFINES clause and the item being 
redefined. Also, the source of error 
may be the definition of another data 
description entry with a lower level 
number appearing between the data 
description entry containing the 
REDEFINES clause and the item being 
redefined. The compiler ignores the 
REDEFINES clause and continues 
processing the data description entry. 


ILLEGAL TO REDEFINE ANOTHER REDEFINITION. 


The REDEFINES clause specifies the 
redefinition of a data item whose data 
description entry contains a REDEFINES 
clause itself. The compiler ignores the 
REDEFINES clause and continues 


processing the data description entry. 


ILLEGAL TO REDEFINE A COBOL TABLE. 


The REDEFINES' clause specifies the 
redefinition of a data item whose data 
description entry contains an OCCURS 
clause. The compiler ignores’ the 
REDEFINES clause and continues 
processing the data description entry. 


-REDEFINES. APPLIED’TO VARIABLE LENGTH DATAITEM. 


The compiler detects an application of 
the REDEFINES clause to a data item 
whose length is variable at run time 
because it has a subordinate data item 
whose data description entry contains an 
OCCURS DEPENDING ON clause. The 
application of the REDEFINES clause to 
such a data item is syntactically 
invalid. The compiler ignores the 
REDEFINES clause and continues 
processing the data description entry. 


ILLEGAL IN REDEFINITION. 


The compiler detects a redefinition that 
contains a data description entry 
declared with an OCCURS DEPENDING ON 
clause. The OCCURS DEPENDING ON clause 
causes the redefinition to contain a 
data item whose length is variable at 
run time. The DEPENDING ON phrase is 
ignored and processing continues. 
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DIAGNOSTIC ERROR MESSAGES 


PICTURE EXCEEDS 3 CHARACTERS. PIC X ASSUMED. 


The unexpanded PICTURE string exceeds 39 
characters in length. The compiler 
ignores the user-supplied PICTURE and 
treats the data item as alphanumeric 
with a "PICTURE X" declaration. 


FILENAME MUST FOLLOW .CLOSE VERB. 


The data item following the CLOSE verb 
was not a file-name. Fatal. 


-NO. MUST FOLLOW .WITH. IT IS ASSUMED. 


The keyword NO is missing in the WITH NO 
REWIND phrase of the CLOSE statement. 
NO is assumed present. 


-REWIND. MUST FOLLOW .NO. IT IS ASSUMED. 
The WITH NO REWIND phrase of the CLOSE 


Statement must be completely specified. 
It is assumed present. 


-REMOVAL. MUST FOLLOW .FOR. IT IS ASSUMED. 


The FOR REMOVAL phrase of the CLOSE 
Statement must be completely specified. 
It is assumed present. 


-LOCK. OMITTED AFTER .WITH. IT IS ASSUMED. 


The keyword WITH in a CLOSE statement is 
recognized but is not followed by one of 
the keywords NO or LOCK. The WITH LOCK 
phrase is assumed present. 


DATANAME SPECIFIED WHERE FILENAME EXPECTED. 


The name used in an I/O verb to 
reference a file was not a file name but 
was some other data-name. Fatal. 


FILENAME MUST FOLLOW MODE SPEC. IN .OPEN. 
The OPEN statement does not reference a 
valid file name where a file-name 
reference is expected. Fatal. 
ILLEGAL MODE SPECIFIED AFTER .OPEN. VERB. 
One of the OPEN mode keywords INPUT, 
OUTPUT, I-O, or EXTEND is’ required 
immediately after the OPEN verb. Fatal. 
-END. MUST FOLLOW .AT.. IT IS ASSUMED. 
The keyword END was omitted in the AT 


END phrase of the READ statement. The 
AT END phrase is assumed present. 
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DIAGNOSTIC ERROR MESSAGES 


FILENAME MUST FOLLOW .READ. VERB. 


Either the file-name was omitted 
following the READ verb or the data item 
following the READ verb is not a valid 
file-name reference. Fatal. 


DATANAME OMITTED AFTER .INTO. IN .READ. 
The data-name reference following the 
INTO keyword of the READ statement was 
omitted. Fatal. 

RECORDNAME MUST FOLLOW .WRITE. OR .REWRITE. 
The #1 record-name reference immediately 
following the WRITE or REWRITE verb was 
omitted. Fatal. 

STATEMENT IGNORED DUE TO ILLEGAL RECORDNAME. 


The data-name immediately following the 
WRITE or REWRITE verb is not ava gl 


record-name reference. Fatal. 


laA 
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-ADVANCING. OPTION OMITTED IN .WRITE. 1 ASSUMED. 


A data-name reference, numeric integer 
literal reference, or the keyword PAGE 
was not recognized in the BEFORE/AFTER 
ADVANCING phrase of the WRITE statement. 
A numeric integer literal value of 1 is 
assumed. 


-EOP. MUST FOLLOW .AT.. IT IS ASSUMED. 


The keyword EOP was omitted in the AT 
EOP phrase of the WRITE statement. The 
AT EOP phrase is assumed present. 


DATANAME OMITTED AFTER .FROM. 
The data-name reference following’ the 
FROM keyword of the WRITE or REWRITE 
statement was omitted. Fatal. 


-ADVANCING. INTEGER TOO BIG. TRUNCATED TO 63. 


The numeric integer in the BEFORE/AFTER 
ADVANCING phrase of the WRITE statement 
is greater than 63. 63 is assumed. 


~NO REWIND. ILLEGAL WITH .I0. OR .EXTEND. MODE. 
An OPEN statement with the I-O or EXTEND 


mode specified cannot have the NO REWIND 
phrase also specified. Fatal. 
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ILLEGAL .ADVANCING. DATANAME. 1 IS ASSUMED 


The data-name in the BEFORE/AFTER 
ADVANCING phrase of the WRITE statement 
is not an elementary numeric integer 
data-name reference. A numeric integer 
literal value of 1 is assumed. 


,; FILENAME MUST FOLLOW .DELETE. VERB. 


Either the file-name was omitted 
following the DELETE verb or the data 
item following the DELETE verb is not a 
valid file-name reference. Fatal. 


FILENAME MUST FOLLOW .START. VERB. 


Either the file name was omitted 
following the START verb or the data 
item following the START verb is not a 
valid file name reference. Fatal. 


~-LESS. OMITTED AFTER .NOT. IN .START. ASSUMED. 


The keyword LESS is omitted after NOT in 
the relational condition of the START 
statement. LESS is assumed present. 


DATANAME OMITTED IN .KEY IS. PHRASE. ASSUMED. 


The RELATIVE KEY data-name for the 
referenced file was omitted in the KEY 
IS phrase of the START statement. The 
RELATIVE KEY data-name is assumed 
present. 


RELATIONAL WORD OMITTED AFTER .KEY IS. PHRASE. 


None of the relational keywords EQUAL, 
GREATER, or NOT was recognized following 
the KEY IS phrase of the START 
statement. Fatal. 


TERMINATOR IGNORED IN .I0 CONTROL. PARAGRAPH. 


A clause is terminated by a period, but 
a header does not follow in Area A. The 
period is ignored. The compiler assumes 
it is still in the I-O-CONTROL 
paragraph. 


TERMINATOR IGNORED IN .SPECIAL NAMES. PARAGRAPH 


A clause is terminated by a period, but 
is not followed by a header in Area A, 
The period is ignored, and the compiler 
continues processing the SPECIAL-NAMES 
paragraph. 
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-NATIVE. MISSING IN SPECIAL NAMES CLAUSE. 


The alphabet-name clause does not 
contain NATIVE or STANDARD-1. The 
alphabet-name clause is ignored. 


SYNTAX ERROR IN .OBJECT COMPUTER. PARAGRAPH. 


The OBJECT-COMPUTER paragraph contains 
an unrecognizable word. The compiler 
scans over all words until a word is 
found in Area A. . 


TERMINATOR OMITTED IN .OBJECT COMPUTER. PARA. 


The OBJECT-COMPUTER paragraph is not 
terminated by a period. The compiler 
scans over all words until a word is 
found in Area A. 


DATANAME FOLLOWING .KEY IS. PHRASE IS ILLEGAL. 


The data-name following the KEY is 
phrase of the START statement is not a 
RECORD KEY associated with the 


referenced indexed file, nor is it 
subordinate to a RECORD KEY whose 
leftmost character position corresponds 
to its own leftmost character position. 
Fatal. 


INVALID USAGE ON CONDITIONAL VARIABLE. 


The level 88 condition variable cannot 
be defined as USAGE INDEX. 


ILLEGAL SEPARATOR IN COBOL STATEMENT. IGNORED. 


An illegal character was detected 
between two consecutive words of a COBOL 
statement. The illegal character is 
ignored. 


ILLEGAL CHARACTER FOUND WITHIN A COBOL WORD. 


Illegal characters were found in an 
alphanumeric COBOL word, but not in an 
alphanumeric literal. The illegal 
characters are replaced by dollar signs 
in the internal representation of the 
COBOL word. 


UNRECOGNIZABLE TEXT FOUND IN COBOL STATEMENT. 


In scanning the source text, the 
compiler was unable to recognize an 
alphanumeric COBOL word (a keyword or 
user-defined word), an alphanumeric 
literal, or a numeric literal. The 
error is not internally corrected and 
usually will cause further error 
messages. 
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DIAGNOSTIC ERROR MESSAGES 


COBOL WORD BEGINS WITH OR ENDS IN HYPHEN. 


In attempting to recognize a keyword or 
user-defined word, the compiler has 
detected that the COBOL word begins or 
ends with a hyphen. 


NONNUMERIC LITERAL TOO LONG. TRUNCATED TO MAX. 


An alphanumeric literal greater than 132 
characters in length is detected. The 
literal is truncated on _ the right, 
retaining the first 132 characters as 
the literal. 


COBOL SOURCE LINE TOO LONG. TRUNCATED TO MAX. 


The indicated COBOL source line contains 
more than 65 characters in terminal 
format. The excess characters are 
ignored, and only those characters in 
the printed COBOL source line are 
retained. 


-BY. OMITTED IN REPLACING OPTION. COPY IGNORED. 


The keyword BY was not found in a 
COPY...REPLACING statement. The 
statement is ignored. 


TERMINATOR OMITTED IN .COPY. IT IS ASSUMED. 


The required period terminating the COPY 
Statement is omitted. It is assumed 
present. 


-LINAGE. CLAUSE DATANAME MUST BE AN INTEGER. 


A data-name referenced in the LINAGE 
clause of the FILE SECTION is defined 
with decimal places in the 
WORKING-STORAGE SECTION. 


A numeric data-name referenced in the 
LINAGE clause of the FILE SECTION is 
defined as a signed data item in the 
WORKING-STORAGE SECTION. 


Truncation of high-order information 
during a MOVE or an arithmetic operation 
upon a receiving field is possible. 
This,is an observation only. 
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DIAGNOSTIC ERROR MESSAGES 


POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. 


Truncation of low-order information 
during a MOVE or an arithmetic operation 
upon a receiving field is possible. 
This is an observation only. 


PD HEADER NOT FOLLOWED BY AN AREA A WORD. 


OPEN OPTIONAL FILES ONLY 


EXPECTED 


EXPECTED 


-RELATIVE KEY. 


The word following the PROCEDURE 
DIVISION header does not begin in Area 
A. The compiler scans over all words 
until a word is found in Area A. 


IN .INPUT. MODE. 


An OPTIONAL file can be OPENed in INPUT 
mode only. The compiler assumes that 
the OPTIONAL file is OPENed in INPUT 
mode. 


A data-name referenced in a FILE STATUS 
phrase of a SELECT clause in the 
FILE-CONTROL paragraph is not defined in 
the WORKING-STORAGE SECTION of the DATA 
DIVISION. 


-VALUE OF ID. DATANAME NOT DEFINED. 


-LINAGE. CLAUSE 


The data-name referenced in a VALUE OF 
ID clause of an FD is not defined in the 
WORKING-STORAGE SECTION of the DATA 
DIVISION. Fatal. 


DATANAME NOT DEFINED. 


A data-name referenced in the LINAGE 
clause of the FILE SECTION is not 
defined in the WORKING-STORAGE SECTION 
of the DATA DIVISION. 


DATANAME HAS INVALID CLASS. 


A data-name referenced in a RELATIVE KEY 
phrase of a SELECT clause in the 
FILE-CONTROL paragraph is defined with 
non-numeric class in the WORKING-STORAGE 
SECTION. 


-RELATIVE KEY. DATANAME HAS INVALID CLASS. 


A data-name referenced in a RELATIVE KEY 
phrase of a SELECT clause must not be 
defined with INDEX usage in the 
WORKING-STORAGE SECTION. 
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DIAGNOSTIC ERROR MESSAGES 


KEY. DATAITEM IS TOO LONG. 


-RELATIVE KEY. DATANAME 


-FILE STATUS. DATANAME 


-FILE STATUS. DATA NAME 


LENGTH OF 


- VALUE OF 


- VALUE OF 


LENGTH OF 


~-FILE STATUS. 


ID. DATANAME 


ID. DATANAME 


»- VALUE OF ID. 


A numeric integer data-name referenced 
in a RELATIVE KEY phrase is defined with 
more than eight digits of precision in 
the WORKING-STORAGE SECTION. 


MUST BE AN INTEGER. 


A numeric data-name referenced in a 
RELATIVE KEY phrase is defined with 
decimal places in the WORKING-STORAGE 
SECTION. 


HAS INVALID CLASS. 


A data-name referenced in a the FILE 
STATUS phrase of a SELECT clause must be 
defined in with DISPLAY usage in the 
WORKING-STORAGE SECTION. 


HAS INVALID USAGE. 


A data-name referenced ina FILE STATUS 
phrase of a SELECT clause is defined 
with DISPLAY USAGE in the 
WORKING-STORAGE SECTION. 


DATAITEM IS ILLEGAL. 


An alphanumeric data-name referenced in 
a FILE STATUS phrase of a SELECT clause 
must be defined in the WORKING-STORAGE 
SECTION as an alphanumeric variable 
consisting of two characters. 


HAS INVALID CLASS. 


A data-name referenced in a VALUE OF ID 
clause of an FD is defined with 
non-alphanumeric class in the 
WORKING-STORAGE SECTION. 


HAS INVALID USAGE. 


A data-name referenced in a VALUE OF ID 
clause of an FD must be defined with 
DISPLAY usage in the WORKING~STORAGE 
SECTION. 


DATAITEM IS ILLEGAL. 


An alphanumeric data-name referenced in 
a VALUE OF ID clause of an FD must be 
defined in the WORKING-STORAGE SECTION 
as an alphanumeric variable whose 
length, L, falls in the range 9<=L<=49 
characters. 
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DIAGNOSTIC ERROR MESSAGES 


-LINAGE. CLAUSE DATANAME HAS INVALID CLASS. 


A data-name referenced in the LINAGE 
clause of the FILE SECTION is defined 
with non-numeric class in the 
WORKING-STORAGE SECTION. 


-LINAGE. CLAUSE DATANAME HAS INVALID USAGE. 
A data-name referenced in the LINAGE 
clause of the FILE SECTION must be 
defined with COMPUTATIONAL USAGE in the 
WORKING-STORAGE SECTION. 

INVALID RECEIVING OPERAND IN .SET.. IGNORED. 


A receiving operand of a SET statement 
is invalid. Fatal. 


NO RECEIVING OPERAND SPECIFIED IN .SET.. 


No receiving operands are specified in a 
SET statement. Fatal. 
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ERAND AFTER .TO. IN .SET.. 


A SET statement has no valid sending 
operand. Fatal. 


ILLEGAL SYNTAX IN .SET. STATEMENT. 
The words TO, UP or DOWN do not follow 
the receiving operands of a SET 
statement. Fatal. 


-BY. MUST FOLLOW .UP. OR .DOWN.. ASSUMED. 


The keyword BY does not follow the word 
UP or DOWN in a SET statement. BY is 
assumed present. 


OMITTED OR ILLEGAL OPERAND AFTER .BY. IN .SET.. 
The operand following the UP BY or DOWN 
BY phrase in a SET statement is invalid 
Or omitted. Fatal. 

NO OPERANDS SPECIFIED 


No operands were recognized following 
the keyword DISPLAY. Fatal. 


SETTING INDEX NAME OUT OF RANGE. .SET. IGNORED. 
A SET statement is attempting to set an 


index name using a literal that is too 
large. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


-IF. TRUE PATH OMITTED. ASSUME .NEXT SENTENCE.. 


CONFLICTING SIGN SYMBOLS 


ZERO SUPPRESSION CONFLICTS IN PICTURE 


ILLEGAL CHARACTER IN THE 


-BLANK WHEN ZERO. 


PARENTHESIZED SPECIFIER EXCEEDS 18 


SPECIFIER MISSING INSIDE 


The true path code is omitted from the 
IF statement. NEXT SENTENCE is assumed 
as the true path of the IF statement. 

IN PICTURE STRING. 


The compiler recognizes both the + and - 


sign symbols in this PICTURE string. 
The compiler ignores the user-supplied 
PICTURE and treats the data item as 
alphanumeric with a "PICTURE x" 
declaration. 

STRING. 


The compiler recognizes both the Z and * 
zero suppression symbols in this PICTURE 


string. The compiler ignores the 
user-supplied PICTURE and treats’ the 
data item as alphanumeric with a 
"PICTURE X" declaration. 

PICTURE STRING. 

A character that is not in the PICTURE 


String character set is recognized in 
this PICTURE by the compiler. The 
compiler ignores the user-supplied 
PICTURE and treats the data item as 
alphanumeric with a "PICTURE x" 
declaration. 
CONFLICTS WITH ZERO SUPPRESS. 

A BLANK WHEN ZERO clause is recognized 
with a zero suppression field specified 
in the PICTURE string. The compiler 
ignores the BLANK WHEN ZERO clause and 


continues with its processing. 
DIGITS. 


The specification contained inside the 
Parentheses of a PICTURE string exceeds 
18 digits in length. The compiler 
ignores the user-supplied PICTURE and 
treats the data item as alphanumeric 
with a "PICTURE X" declaration. 


PARENTHESES. 


inside 
is 


The specification contained 
parentheses of a PICTURE string 
missing. The compiler ignores the 
user-supplied PICTURE and treats’ the 
data item as alphanumeric with a 
"PICTURE X" declaration. 
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433 ILLEGAL SYMBOL PRECEDES LEFT PAREN. IN PICTURE. 


The compiler recognizes an S, V, CR, DB, 


or Mg character preceding a left 
parenthesis in a PICTURE string. The 
error is ignored and processing 


continues. 
434 TERMINATOR OMITTED IN .NOTE. PARAGRAPH. 


The compiler detected a NOTE paragraph 
that does not end with a period. 


435 INVALID OPERAND IN .VARYING. OR .AFTER. PHRASE. 


The expected operand is not a valid name 
reference in the VARYING or AFTER phrase 
of this PERFORM VARYING statement. 
Fatal. 


436 INVALID OPERAND IN .FROM. OR .BY. PHRASE. 


The FROM or BY phrase of a PERFORM 
VARYING statement does not contain a 
valid operand reference. Fatal. 


437 TOO MANY .AFTER. PHRASES IN .PERFORM. STATEMENT. 


The compiler detects more than two AFTER 
phrases in the PERFORM VARYING statement 


being compiled. Fatal. 
449 .FROM. OR .BY. OR .UNTIL. MISSING IN PERFORM. 


The compiler detects the omission of the 
keywords FROM, BY, or UNTIL in the 
PERFORM VARYING statement. Fatal. 


44] ILLEGAL CONDITION EXPRESSION IN THE PERFORM. 


The compiler detects an invalid 
condition expression in the PERFORM 
statement. Fatal. 


442 NONPOSITIVE LITERAL IN .FROM. OR .BY. PHRASE. 
The compiler detects a non-positive, 


numeric integer literal in this PERFORM 
statement. Fatal. 


443 INVALID RELATION CONDITION IN .SEARCH ALL. 
The compiler detects either a syntax 
error or an invalid operand in the 


restricted form of a relation condition 
in the SEARCH ALL statement. Fatal. 
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DIAGNOSTIC ERROR MESSAGES 


NONINTEGER DATA CONFLICTS WITH INDEXNAME USAGE. 


IMPLICIT 


TOO MANY 


The compiler detects a non-integer data 
item reference in a PERFORM VARYING 
statement in which the VARYING, AFTER, 
and/or FROM phrase contains an 
index-name reference. Fatal. 

NCE TO BAD CONDITION VALUES. 


ET - FS et we oe ee 


Through a reference to a condition-name, 
the compiler detects a reference to an 
associated condition-value that is 
improperly declared in the Data 
Division. Fatal. 


REFERENCE TO BAD CONDITION VARIABLE. 


Through a reference to a condition-name, 
the compiler detects that the associated 
condition-variable is improperly 
declared in the Data Division. Fatal. 


NAMES IN COBOL PROGRAM. RECOMPILE. 


The COBOL program being compiled has too 
many data-names Or procedure~-names. 
This condition has caused a compiler 
table to overflow, aborting the 
compilation. The program should be 
recompiled using the "/SYM:N" switch to 
reserve more space for the compiler 
symbol tables. 


458 REFERENCE TO UNDEFINED DATANAME. IGNORED. 


451 


The COBOL statement being compiled 
contains a reference to an undefined 
data-name. The compiler ignores’ the 
reference. This diagnostic may be 
issued in conjunction with other 


diagnostics for the erroneous statement. 
BPatal 


auUueusre 


QUALIFIED REFERENCE ILLEGAL IN THIS CONTEXT. 


The compiler detects a qualified 
reference in a context in which an 
unqualified reference is required. The 
compiler permits the qualified reference 
in this context and continues with the 
compilation of the statement containing 
the reference. 
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452 QUALIFIER OMITTED IN QUALIFIED REFERENCE. 


453 


454 


455 


456 


457 


A data-name is omitted after the keyword 
OF or IN in a qualified reference in the 
COBOL statement being compiled. The 
reference is ignored. This diagnostic 
may be issued in conjunction with other 
diagnostics for the statement in error. 


TOO MANY QUALIFIERS IN QUALIFIED REFERENCE. 


The compiler detects more than 48 
qualifiers in a qualified reference. The 
excess qualifiers are ignored in the 
reference. 


UNDEFINED QUALIFIER IN QUALIFIED REFERENCE. 


COBOL STATEMENT CONTAINS 


The compiler detects a qualified 
reference in which a quaiifier isa 
reference to an undefined data-name. The 
compiler ignores the entire qualified 
reference. This diagnostic may be issued 
in conjunction with other diagnostics 
for the erroneous statement containing 
the reference. 


AMBIGUOUS REFERENCE. 


The compiler detects a reference to 
COBOL data that is not uniquely 
referenceable through qualification. The 
compiler uses a reference that satisfies 
the reference in the text of the COBOL 
program. This diagnostic may be issued 
in conjunction with other diagnostics 
for the statement in error. 


DATANAME REFERENCE EXPECTED IN THIS CONTEXT. 


The compiler detects a reference to a 
data item that is not alphabetic, 
numeric, alphanumeric-edited, 
alphanumeric, or numeric-edited. The 
context of this reference requires that 
the reference be to one of these classes 
of data items. This diagnostic may be 
issued in conjunction with other 
diagnostics for the statement in error. 


ILLEGAL REFERENCE DETECTED IN THIS CONTEXT. 


The compiler detects a reference to an 
item that is invalid in the context of 
its usage. This diagnostic may be 
issued in conjunction with other 
diagnostics for the statement in error. 
Fatal. 
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EXTRA OPENING QUOTE ON LITERAL IS IGNORED. 


The compiler detects a superfluous quote 
at the beginning of a non-numeric 
literal specification. The compiler 
ignores the extra quote and continues 
processing the non-numeric literal. 


PROGRAM NAME MUST BE A NONNUMERIC LITERAL. 


The program-name literal following the 
key word CALL is not a nonnumeric 
literal. Fatal. 


LITERALS ARE ILLEGAL IN ARGUMENT LIST OF .CALL.. 


Literals are not allowed in the argument 
list of a CALL statement. Fatal. 


ARGUMENT LIST OMITTED AFTER .USING. IN .CALL.. 


The required argument list is missing 
after the key word USING in the CALL 
Statement. Fatal. 


ILLEGAL SYNTAX IN .CODE SET. CLAUSE. IGNORED. 


A valid alphabet-name reference is 
omitted in the CODE-SET clause. The 
compiler ignores the CODE-SET clause and 
continues to process’ the remainder of 
the FD. 


DATANAME IN .KEY IS. PHRASE NOT ALPHANUMERIC. 


The data-name following the KEY Is 
phrase in a START statement referencing 
an indexed file must be alphanumeric. 
Fatal. 


-RECORD KEY. DATAITEM LENGTH GREATER THAN 255. 


A data-name referenced in a RECORD KEY 
or ALTERNATE RECORD KEY phrase of a 
SELECT clause in the FILE-CONTROL 
Paragraph must be defined in the FILE 
SECTION as an item whose length is’ less 
than or equal to 255. 


DATANAME IN .KEY IS PHRASE IS SUBSCRIPTED OR INDEX. 


The data-name following the KEY IS 
phrase in a READ or START statement 
referencing an indexed file must not be 
subscripted or indexed. Fatal. 
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-RECORD KEY. DATAITEM MUST NOT BE A COBOL TABLE. 


A data-name referenced in a RECORD KEY 
Or ALTERNATE RECORD KEY phrase ofa 
SELECT clause in the FILE-CONTROL 
paragraph must not be defined in the 
FILE SECTION with an OCCURS clause or be 
subordinate to an item with an OCCURS 
clause. 


-RECORD. OMITTED FROM .ALTERNATE RECORD. ASSUMED. 


The reserved word RECORD is missing from 
the ALTERNATE RECORD KEY clause. The 
error is ignored. 


UNDEFINED .ALTERNATE RECORD KEY. DATANAME. 


The data-name given in an ALTERNATE 


RECORD KEY ciause has not been defined 
in the Data Division. 


-ALTERNATE RECORD KEY. CLAUSES ARE SEPARATED. 


In the SELECT statement the ALTERNATE 
RECORD KEY clauses are interleaved among 
the other clauses. The ALTERNATE RECORD 
KEY clauses should follow one another 
with no intervening clauses. This error 
is ignored. 


LINKAGE SECTION ITEM APPEARS TWICE IN .USING.. 


A LINKAGE SECTION data item must not 
appear more than once in the USING 
phrase of a PROCEDURE DIVISION USING 
header. Fatal. 


ILLEGAL .SEGMENT-LIMIT. VALUE IGNORED. 
The segment-limit is not a numeric 
literal or is a numeric literal whose 
value is outside of allowed 
segment-limit range. 


INTEGER 1 BEYOND AREA A TREATED AS LEVEL NUMBER. 


An $1 level item was detected beyond 
Area A and accepted as if in Area A. 


MULTIPLE PICTURES FOR SAME ITEM. LAST USED. 
A data item has more than one PICTURE 


clause. The compiler used the last 
PICTURE clause specified. 
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CLOSING PARENTHESIS MISSING IN PICTURE. 


The right parenthesis is missing in the 
PICTURE string. The compiler uses the 
last four characters of the PICTURE 
string. 


NOT A SUBPROGRAM .PROGRAM. IGNORED. 


An EXIT PROGRAM has been detected, but 
the COBOL program being compiled is not 
a subprogram. Because EXIT PROGRAM is 
meaningful only in a subprogram, the 
word PROGRAM is ignored, and the 
statement is treated as if it were a 
simple EXIT statement. 


EXPANDED PICTURE STRING TOO LONG. PIC X ASSUMED. 


SPECIFIER OMITTED BEFORE 


SECTION NO. GREATER THAN 


The expansion of a PICTURE string 
specification produces a string that 
exceeds implementation limitations. The 
compiler ignores the user-supplied 
PICTURE and treats the data item as if 
it had a "PICTURE X" declaration. 


LEFT PAREN. IN PIC. 


The first character of a PICTURE string 
is a left parenthesis. The compiler 
ignores the user-supplied PICTURE and 
treats the data item as alphanumeric 
with a “PICTURE X" declaration. 


49 TREATED AS 49. 
A segment number greater than 49 follows 


the word SECTION. The segment is 
treated as if it were 49. . 


INVALID ITEM LENGTH IN PARENTHESES OF PICTURE. 


VALUE CLAUSE NOT ALLOWED 


The parenthesized length specifier in a 
PICTURE contains non-numeric characters. 
The compiler ignores the user-supplied 
PICTURE and treats the data item as 
alphanumeric with a "PICTURE X" 
declaration. 


IN LINKAGE SECTION. 


The VALUE clause cannot appear in data 
items in the LINKAGE SECTION. The only 
place the VALUE clause can appear in the 
LINKAGE SECTION is in a condition name 
definition. 


OPERAND IN .USING. MUST BE LINKAGE SECTION ITEM. 


Only level §1 or 77 LINKAGE SECTION 


4 ~ Pi mueig I | o- ~ £ 
items May appear in the USING phrase of 


a PROCEDURE DIVISION header. Fatal. 
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MULTIPLE FLOATING FIELDS IN NUMERIC EDIT ITEM. 


The PICTURE string contains multiple 
floating fields. The compiler ignores 
the user-supplied PICTURE and treats the 
data item as alphanumeric with a 
"PICTURE X" declaration. 


MULTIPLE ZERO SUPPRESS FIELDS IN PICTURE STRING. 


Multiple zero suppression fields are 
detected in a PICTURE string. The 
compiler ignores the user-supplied 
PICTURE and treats the data item as 
alphanumeric with a "PICTURE X" 
declaration. 


ZERO SUPPRESSION ILLEGAL WITH FLOATING FIELD. 


The PICTURE string contains both 
floating and zero suppression fields. 
The compiler ignores the user-supplied 
PICTURE and treats the data item as 
alphanumeric with a "PICTURE X" 
declaration. 


ILLEGAL SYNTAX IN PICTURE STRING. 


The PICTURE string is not specified 
correctly according to the rules of 
PICTURE string syntax. The compiler 
ignores the user-supplied PICTURE and 
treats the data item as alphanumeric 
with a "PICTURE X" declaration. 


MULTIPLE DECIMAL POINTS IN PICTURE. 


The PICTURE string contains multiple 
decimal point specifications (V's, P's, 
Or periods). The compiler ignores’ the 
user-supplied PICTURE and. treats’ the 
data item as alphanumeric with a 
"PICTURE X" declaration. 


OPERAND IN USING MUST BE LEVEL #1 OR 77. 


Only level $1 or 77 LINKAGE SECTION 
items may appear in the USING phrase of 
a PROCEDURE DIVISION header. Fatal. 


INVALID USAGE. IGNORED. 
The USAGE clause contains an invalid 


word. The compiler ignores the entire 
USAGE clause. 
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MULTIPLE USAGE CLAUSES. LAST USED. 


MULTIPLE OCCURS CLAUSES. 


The defined data-name has multiple USAGE 
clauses specified. The last USAGE 
clause specified is used by the 
compiler. 


LAST USED. 
The defined data-name has multiple 


OCCURS clauses specified. The compiler 
uses the last OCCURS clause specified. 


OCCURS SPECIFICATION ERROR. 1 ASSUMED. 


DATANAME OMITTED IN DATA 


The integer entry of the OCCURS clause 
is either non-numeric or non-integer or 
is not in the range 1 to 4995. The 
compiler assumes an integer value of l. 


DESCRIPTION ENTRY. 


The data-name declaration is omitted 
after a level-number in the data 
description entry. The compiler supplies 
a system-defined name and proceeds with 
the processing of the data description 
entry. The system-defined name is 
transparent and, thus, inaccessible to 
the user. 


INVALID INDEX NAME. IGNORED. 


The compiler did not recognize a valid 
index name in the INDEXED BY phrase. 
The compiler ignores the INDEXED BY 
phrase. 


538 USAGE OPTION NOT YET IMPLEMENTED. IGNORED. 


531 


TERMINATOR OMITTED AFTER 


The compiler detected COMP-1l in the 
USAGE clause. This option is not 
implemented and is ignored. The default 
USAGE of DISPLAY is used by the 
compiler. 


DATAITEM DESCRIPTION. 
A data description entry in the DATA 
DIVISION is not terminated by a period. 


The compiler assumes the period is 
present and continues processing. 
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INVALID SIGN IN NUMERIC PICTURE. 


The sign character S is detected in a 


position other than the leading 
character position of a numeric PICTURE 
string. The compiler ignores’ the 


user-supplied PICTURE and treats’ the 
data item as alphanumeric with a 
"PICTURE X" declaration. 


PICTURE CLAUSE OMITTED ON ELEMENTARY ITEM. 


An elementary item is recognized with 
its PICTURE clause omitted in the 
description. The compiler treats the 
data item as alphanumeric with a PICTURE 
X declaration. 


NUMERIC ITEM EXCEEDS 18 DIGIT MAX. TRUNCATED. 


A numeric field is defined in this 
PICTURE with more than 18 digits of 
precision. The numeric field is 
truncated to 18 digits. 


COMP ITEM EXCEEDS 18 DIGITS. ASSIGN 4 WORDS. 


A COMPUTATIONAL data item exceeds 18 
digits in its specification. The 
compiler truncates it and allocates four 
words for its run-time storage. 


INDEX ITEM HAS ILLEGAL CLAUSE. 


The compiler recognized a JUSTIFIED, 
SYNCHRONIZED, VALUE, PICTURE, or SIGN 
clause on a data-item description that 
has INDEX USAGE. The compiler ignores 
the offensive clause. 


NUMERIC VALUE FOR DISPLAY ITEM. IGNORED. 


The VALUE clause specifies numeric value 
initialization for a non-numeric 
data-item that is defined with DISPLAY 
USAGE. The VALUE clause is ignored. 


VALUE TOO LONG. TRUNCATED. 


The non-numeric literal in the VALUE 
clause is longer than the associated 
data-item. The literal is truncated on 
the right to fit in the storage 
allocated to the data-item. 


CLAUSE DUPLICATION. IGNORED. 
This clause has been previously 


recognized for this item. The duplicate 
clause is ignored. 
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INVALID WORD IN .BLANK WHEN ZERO.. IGNORED. 


The keyword ZERO was not recognized in 
the BLANK WHEN ZERO clause. The entire 
clause is ignored. 


LEVEL NUMS UNEQUAL IN .REDEFINES. CLAUSE IGNORED. 


A REDEFINES clause attempts to ed 
two items of different level oes 


The REDEFINES clause is ignored. 


fine 
rs. 


e 
An 
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POSSIBLE OVERLAP OF DEPENDING ON ITEM AND TABLE. 


LEVEL ILLEGAL AFTER 77. 


The DEPENDING ON item and variable 
length table are both defined in the 
LINKAGE SECTION. Because LINKAGE 
SECTION items are associated with data 
items appearing in a CALL statement, 
there is no way at compile time to 
ensure that the DEPENDING ON items’ and 
table do not overlap. The COBOL 
run-time OTS does not check for overlap 
of the DEPENDING ON item and the table 
during execution. It is, therefore, 
your responsibility to ensure that 
overlap does not occur. 


TREATED AS @1. 


An invalid level number (#2-49) follows 
a 77 level item. The 77 level item is 
treated as an §1 level item. This 
action can cause further diagnostics if 
it is not a valid group item. 


PERIOD OMITTED AFTER .EXIT PROGRAM. 


The words EXIT PROGRAM are not’ followed 
by a period. The error is ignored. 


-EXIT PROGRAM. NOT LASTSTMT OF SENTENCE. 


REDEFINITION OF .OCCURS. 


An EXIT PROGRAM statement appéars in a 
sequence of statements within a 
sentence. But, it is not the last 
statement. All of the statements 


following it are compiled, but can never 
be executed. 


MATCH ORIGINAL LENGTH. 

The length of a non-#$1 level REDEFINES 
item is not the same as the length of 
the item it REDEFINES. The new length 
is used. 


ITEM. IGNORED. 


Items with OCCURS cannot be 
redefined. REDEFINES is ignored. 
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PROCESSING RESUMES AFTER BAD FD. 


Prior to issuing this message, the 
compiler discovered bad syntax in the FD 
of the FILE SECTION. The compiler at 
that time issued an error message 
identifying the syntax error. Then the 
compiler attempted to recognize another 
FD, the WORKING-STORAGE SECTION header 
or the PROCEDURE DIVISION. Upon 
recognizing one of these three language 
elements, the compiler issues this 
diagnostic to indicate that normal 
processing has resumed. 


INVALID CLAUSE KEYWORD. OTHER CLAUSES SKIPPED. 


A reserved clause keyword was expected 
at this point in a data item description 
entry of the DATA DIVISION, but was not 
recognized by the compiler. The 
compiler skips to the next level number 
data item description. 


INVALID WORD FOLLOWING .VALUE.. IGNORED. 


The VALUE clause contains an invalid 
word for this data description. The 
entire VALUE clause is ignored. 


VALUE CONFLICT. GROUP VALUE USED. 


The VALUE clause assigns a value to an 
item subordinate to a group item that 
also has a VALUE clause. The 
subordinate VALUE clause is ignored. 


LEVEL NUMBER OMITTED. ITEM IGNORED. 


The level number has been omitted in a 
data-item description. All source text 
is ignored up to and including the next 
period. 


NO VALUE AFTER CONDITION NAME. 88 IGNORED. 
An 88 level condition-name has no VALUE 
clause specified. The entire 88 level 
data-item is ignored. 


SYNTAX ERROR IN SWITCH CLAUSE. CLAUSE IGNORED. 


The SWITCH clause has a syntax error in 
its specification. The compiler ignores 
the entire clause. 
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-NO. MISSING IN ADVANCING PHRASE. ASSUMED. 


The keyword NO is missing in the 
ADVANCING phrase of the DISPLAY 
statement. NO is assumed present. 


-ADVANCING. MISSING AFTER .NO.. ASSUMED. 


The keyword ADVANCING is missing in the 
ADVANCING phrase of the DISPLAY 
statement. ADVANCING is assumed 
present. 


DUPLICATE DATANAME DECLARATION DETECTED. 


In the ENVIRONMENT DIVISION and/or DATA 
DIVISION, a data-name is defined that is 
not uniquely referenceable even with 
complete qualification. 


ILLEGAL PARAGRAPH HEADER ID DIV. PAR IGNORED. 


An illegal paragraph header appears’ in 
the IDENTIFICATION DIVISION. The 
paragraph is ignored. 

ILLEGAL PARAGRAPH HEADER ENV DIV. PAR IGNORED. 


An illegal paragraph header appears in 
the ENVIRONMENT DIVISION. The paragraph 
is ignored. 

NUMERIC LITERAL ILLEGAL ON GROUP ITEM. IGNORED. 


A numeric literal is illegal in the 
VALUE clause of a group item. The VALUE 
clause is ignored. 

-ENVIRONMENT. NOT FOLLOWED BY .DIVISION.. 


The word ENVIRONMENT is not followed by 
the word DIVISION. DIVISION is assumed 
present. 

TERMINATOR MISSING AFTER .DATA DIVISION. HEADER. 


The DATA DIVISION header is not followed 

by a_ period. The period is assumed 

present and processing continues. 
TERMINATOR MISSING AFTER PARAGRAPH HEADER. 


A paragraph header in the IDENTIFICATION 


or ENVIRONMENT DIVISION is not 
terminated by a period. The period is 
assumed present and processing 
continues. 
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»RENAMES. SPECIFIES STORAGE OVERLAP ON RIGHT. 


In processing the RENAMES clause, the 
compiler detects the condition in which 
the end of the storage allocated to the 
data-name after the THRU keyword is not 
to the right of the end of the _ storage 
allocated to the data-name after the 
RENAMES keyword. The compiler ignores 
the entire RENAMES data description 
entry. 


»SECTION. OMITTED FROM SECTION HEADER. 


An ENVIRONMENT DIVISION section name is 
not followed by the word SECTION. The 
error is ignored. 


TERMINATOR MISSING AFTER SECTION HEADER. 


An ENVIRONMENT DIVISION section header 
is not terminated by a period. The 
error is ignored. 


ILLEGAL LEVEL NUMBER. TREAT AS @1. 


This level number is not an 91-49, 66, 
77, or 88 level number. The ilevel 
number is assumed to be #1. 


TERMINATOR MISSING AFTER ENV DIV HEADER. 


The ENVIRONMENT DIVISION header is not 
terminated by a period. The period is 
assumed present and processing 
continues. 


-DATA. NOT FOLLOWED BY .DIVISION. 


The word DATA is not followed by the 
word DIVISION. DIVISION is assumed 
present. 


ENVIRONMENT DIVISION HEADER OMITTED. 


The program contains no ENVIRONMENT 
DIVISION header. The compiler resumes 
processing at the next paragraph header. 


UNRECOGNIZABLE COBOL PROGRAM FORMAT. ABORT. 


The compiler is unable to recognize the 
reserved word IDENTIFICATION as the 
first word required in a COBOL source 
program. Failure to recognize this 
required reserved word may be due to one 
of the following reasons: 
(1) IDENTIFICATION is, in fact, omitted 
as the first word of the source file, 
(2) the user is attempting to compile a 
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COBOL source program in conventional 
format without . specifying the 


conventional format switch, or (3) the 


user is attempting to compile a file 
that is not a COBOL source program. The 
compiler issues a string of diagnostics 
and then aborts the compilation. 


- IDENTIFICATION. NOT FOLLOWED BY .DIVISION.. 


TERMINATOR OMITTED AFTER 


The word IDENTIFICATION is not followed 
by the word DIVISION. DIVISION is 
assumed present. 


-ID DIVISION. HEADER. 


The IDENTIFICATION DIVISION header is 
not terminated by a period. The period 
is assumed present and processing 
continues. 


- PROGRAMID. EXPECTED AFTER DIVISION HEADER. 


TERMINATOR OMITTED AFTER 


INVALID PROGRAM NAME IN . 


The IDENTIFICATION DIVISION header is 
not followed by the PROGRAM-ID 
paragraph. The error is ignored and 
processing continues. 


-PROGID. PARA HEADER. 


The PROGRAM-ID paragraph-name is not 
terminated by a period. The period is 
assumed present and processing 
continues. 


PROGRAM ID. PARAGRAPH. 


The program name of the PROGRAM-ID 
paragraph contains an invalid character 
Or exceeds the maximum length. The 
error is ignored and processing 
continues. 


TOO MANY FILES FOR LUNS OR TEMPORARY SPACE. 


The compiler has discovered either that 
more than 3@ files are declared in the 
program or that more than 398 SAME RECORD 
AREA clauses are specified in the 
program. The compiler imposes a limit 
of 39 in both cases, because the 
associated compiler and/or object time 
table space is exhausted. 


INVALID WORD SUSPENDS PROCESSING. SCAN FORWARD. 


An unidentifiable word is found where a 
verb is expected. The compiler scans to 
a verb, period, or word in Area A. 


DIAGNOSTIC ERROR MESSAGES 


614 PROCESSING RESTARTS ON VERB. 


Due to a previous syntax error, the 
compiler scanned forward for the next 
verb, period, or Area A word at which to 
resume compilation. The compiler 
recognized a verb and resumes. normal 
compilation at this point. This message 
is an observation only. 


615 PROCESSING RESTARTS ON PROCEDURE NAME. 


Due to a previous syntax error, the 
compiler scanned forward for the next 
verb, period, or Area A word at which to 
resume compilation. The compiler 
recognized an Area A word and resumes 
compilation at this point. This message 
is an observation only. 


616 PROCESSING RESTARTS AFTER TERMINATOR. 


Due to a previous syntax error, the 
compiler scanned forward for the next 
verb, period, or Area A word at which to 
resume compilation. The compiler 
recognized a period and resumes normal 
compilation on the word following the 
period. This is an observation only. 


617 .IDENTIFICATION. KEYWORD NOT IN AREA A. 


The compiler detects that the 
IDENTIFICATION keyword is not in Area 
A. The compiler ignores the error and 
continues processing. 


628 PARAGRAPH TERMINATOR ASSUMED OMITTED. 


A paragraph was terminated without a 
period. The period is assumed and 
processing continues. 


621 .LINAGE. INVALID FOR THIS FILE. CLAUSE IGNORED. 


The LINAGE clause must not be’ specified 
for a file that has RELATIVE or INDEXED 
organization. The LINAGE clause is 
ignored. 


622 TERMINATOR MISSING AFTER PROCEDURE NAME. 


A section or paragraph name is not 
terminated by a period. The period is 
assumed present and processing 
continues. 
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-ELSE DOES NOT HAVE ASSOCIATED .IF.. IGNORED. 


The word ELSE has no associated IF 
statement. The ELSE is ignored. 


VERB EXPECTED TO FOLLOW ELSE... .ELSE. IGNORED. 


A sentence ends with the word ELSE. The 
ELSE is ignored. 


-JUSTIFY. WITH NUMERIC OR EDITED ITEM. IGNORED. 


The JUSTIFIED clause must not be 
specified for a numeric or 
numeric-edited data item. The JUSTIFIED 
clause is ignored. 


»-BLANK WHEN ZERO. ILLEGALLY SPECIFIED. IGNORED. 


The BLANK WHEN ZERO clause must be 
specified only for a numeric or 
numeric-edited data item. The clause is 
ignored. 


INVALID OR MISSING DATANAME AFTER .REDEFINES.. 


The compiler detects the omission of a 
valid data-name reference following the 
keyword REDEFINES. The compiler ignores 
the REDEFINES clause and continues 
processing the data description entry. 


~-REDEFINES. MUST FOLLOW DATA NAME. IGNORED. 


The REDEFINES keyword appears in the 
wrong position of a data description 
entry. The REDEFINES clause is ignored. 


DEPTH OF NESTED .IF. EXCEEDS LIMIT. 


DUPLICATE PROCEDURE NAME 


REFERENCE TO UNDEFINED PA 


A nested IF statement has exceeded the 
max imum depth of 3f levels. The 
compiler ignores nesting beyond this 
depth. 


DETECTED. 


In the Procedure Division, a paragraph 
or section-name is defined that is not 
uniquely referenceable even with 
qualification. 


RAGRAPH NAME. 


In the Procedure Division, an explicit 
qualified reference is Made to a 
paragraph-name that is undefined in the 
section specified by the qualifier. 
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FILENAME LITERAL TOO LONG. TRUNCATED. 


A file specification in the ASSIGN 
clause exceeds 4f characters in length. 
It is truncated to 4@ characters. 


ILLEGAL SYNTAX IN .GO TO. STATEMENT. 


The compiler detects illegal syntax in 
the GO TO statement. Fatal. 


INVALID INTEGER OR DATANAME. 


In the LINAGE clause, the compiler 
failed to recognize a non-negative 
integer literal or a numeric’ integer 
data-name. This phrase of the LINAGE 
clause is ignored. 


at 
ON phrase 
procedure-name. Fatal. 


INVALID WORD FOLLOWS .DATA DIVISION. 


The word following the DATA DIVISION 
header either does not start in Area A 
Or is not one of the reserved words 
FILE, WORKING-STORAGE, LINKAGE, Or 
PROCEDURE. The compiler skips all 
source text until one of the keywords 
FILE, WORK ING-STORAGE, LINKAGE, or 
PROCEDURE is recognized. 


INVALID WORD IN FILE SECTION. SCAN FORWARD. 


An invalid word was detected in the FILE 
SECTION where the keyword FD is 
expected. The compiler skips all source 
text until one of the keywords FD, 
WORKING-STORAGE, LINKAGE, or PROCEDURE 
is recognized. 


-OMITTED LABELS IGNORED WITH .VALUE OF ID. 


The LABEL RECORDS ARE OMITTED clause is 
ignored if VALUE OF ID is specified for 
a file. STANDARD labels are assumed. 
Warning. 


~-SECTION. EXPECTED AFTER HEADER WORD. 
The keyword SECTION is omitted after the 
word FILE, WORKING-STORAGE, OR LINKAGE 


SECTION. It is assumed present and 
processing continues. 
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TERMINATOR EXPECTED AFTER SECTION HEADER. 


-OF. OR 


The FILE SECTION, WORK ING-STORAGE 
SECTION, or LINKAGE SECTION header is 
not terminated by a period. The period 
is assumed and processing continues. 


-ID. MISSING IN .VALUE OF ID.. 


One or both of the keywords OF or ID is 
omitted in the VALUE OF ID clause. 
Their presence is assumed and processing 
continues. 


ILLEGAL WORD IN AREA A. SCAN FORWARD. 


In the WORKING-STORAGE SECTION, an @1 or 
77 level number or the PROCEDURE keyword 
was expected in Area A, but was not 
recognized. The compiler skips all 
source text until one of the three 
expected language elements is recognized 
in Area A. 


GROUP LEVEL .VALUE. DISALLOWED. 


The VALUE clause on this group item is 
not permitted because a subordinate 
elementary item has a non-DISPLAY usage 
specified or has a SYNCHRONIZED clause 
specified. The group VALUE clause is 
ignored. 


REFERENCED LINKAGE SECTION ITEM NOT ID .PD. USING.. 


This LINKAGE SECTION item has been 
referenced in the PROCEDURE DIVISION. 
However, neither this item nor the level 
G1 to which it is subordinate appeared 
in the PROCEDURE DIVISION USING phrase. 
Only those LINKAGE SECTION items 
appearing in the PROCEDURE DIVISION 
USING phrase, or items subordinate to 
them, may be referenced in the PROCEDURE 
DIVISION of a COBOL program. Fatal. 


652 NON-SEQ FILE IN .MULTIPLE. FILE TAPE. CLAUSE. 


653 


In the I-O CONTROL paragraph, the 
MULTIPLE FILE TAPE clause is specified 
for a file whose organization is not 
SEQUENTIAL. The MULTIPLE FILE TAPE 
clause is ignored for this file. 


~-VALUE. CLAUSE ILLEGAL IN FILE SECTION. 


A VALUE clause is specified for a data 
description entry given in the FILE 
SECTION. The VALUE clause is ignored. 
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SYNTAX ERROR IN CURRENCY 


ILLEGAL CURRENCY SIGN. 


SPECIALNAMES CLAUSE f 


vid 


CLAUSE. 


The alphanumeric literal expected in the 
CURRENCY SIGN clause of the 
SPECIAL-NAMES paragraph is omitted. The 
clause is ignored and the currency sign 
defaults to the dollar sign. 


The alphanumeric literal in the CURRENCY 
SIGN clause is not allowed as_ the 
currency sign either because the literal 
is longer than one character or because 
it is an invalid COBOL currency sign. 
The CURRENCY SIGN clause is ignored, and 
the currency sign defaults to the dollar 
sign. 


VALID. 


An unrecognizable word appears in a 
position where a SPECIAL-NAMES paragraph 
clause keyword is expected. All source 
text is skipped until the next keyword 
is recognized. 


SYNTAX ERROR IN DECIMALPOINT CLAUSE. 


-AFTER. MISSING IN .USE. 


NO .ERROR. OR .EXCEPTION. 


The keyword COMMA is omitted in the 
DECIMAL-~POINT IS COMMA clause of the 
SPECIAL-NAMES paragraph. The clause is 
ignored. 


STATEMENT. ASSUMED. 


The keyword AFTER is omitted in the USE 
Statement. AFTER is assumed present and 
processing continues. 


IN .USE. ASSUMED. 


One of the keywords ERROR or EXCEPTION 
is omitted in the USE statement. The 
missing keyword is assumed present and 
processing continues. 


NO KNOWN CLAUSES IN SPECIALNAMES. 


REDUNDANT .USE. COVERAGE. 


The SPECIAL-NAMES paragraph contains no 
valid clauses. This is an observation 
only. 


PREV. .USE. IGNORED. 
Multiple USE statements have referenced 
the same file. The last USE statement 


specified is then applied to the 
referenced file. Fatal. 
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UNKNOWN OPEN MODE IN .USE. STATEMENT. 


An unrecognizable OPEN mode option was 
specified in the USE statement. Fatal. 


GROUP ITEM HAS BEEN CALLED FILLER. 


A FILLER item cannot have any elementary 
items subordinate to it. The compiler 
replaces the FILLER declaration with a 
system-defined name and proceeds with 
the processing of the newly-named group 


item. The system-defined name is 
transparent and inaccessible to the 
user. 


MISSING ENVIRONMENT DIVISION. 


The program does not contain an 


ENVIRONMENT DIVISION. The compiler 
skips to the DATA DIVISION and continues 
processing. 


DIVISION BY ZERO. 


The divisor of a DIVIDE statement is a 
literal of zero value. The error is 
ignored. 


VALUE NOT PERMITTED WITH THIS ITEM. 


A VALUE clause is recognized in a data 
description entry that contains a 
REDEFINES or an OCCURS clause. The 
VALUE clause is ignored. 


INVALID CONSTANT OR LITERAL FOLLOWING .ALL.. 


The reserved word ALL is not followed by 
a non-numeric literal or a figurative 
constant. ALL is ignored and processing 
continues. 


An unrecognizable word appears where a 
file-name is expected in the USE 
Statement. Fatal. 


FILE NOT CLOSED. 


The referenced file was opened, but 
there was no CLOSE statement detected 


esse aay uauenrw ww 


for this file in the program. 
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SUBJECT OF .ALTER. IS SECTION NAME. 


The ALTER statement references a section 
name. Only paragraph names may be 
altered. If this statement is reached 
during execution, the program will be 
aborted. 


FILE COVERED BY CONFLICTING USE PROCEDURE. 


There was more than one conflicting USE 
procedure specified for the referenced 
file. Fatal. 


DATA DIVISION EXCEEDS ADDRESS RANGE. 


The maximum DATA DIVISION size is 65,535 
bytes. Fatal. 


SUPPLIED VALUE INVALID FOR NUM ITEM. IGNORED. 


The VALUE clause specifies invalid value 
initialization for a numeric data item. 


The compiler ignores the VALUE clause. 
FILE ACCESSED BY VERB REQUIRING REL. OR IDX ORG. 


A file whose organization is SEQUENTIAL 
is referenced by the START or DELETE 
verbs or by an I/O verb that has the 
INVALID KEY clause specified. In all 
these cases, the referenced file must 
have RELATIVE or INDEXED organization. 
Fatal. 


FILE ACCESSED BY VERB REQ. SEQUENTIAL ORG. 


A file whose organization is RELATIVE or 
INDEXED is referenced by an I/O verb 
that has the AT EOP or ADVANCING clauses 
specified. The referenced file must 
have SEQUENTIAL organization. Fatal. 


VERB NOT IMPLEMENTED. 


An ANS 1974 COBOL verb appears that is 
not implemented in this release of the 
compiler. The compiler scans to another 
verb, period, or word in Area A. 


OCCURS ILLEGAL FOR #1 OR 77 ITEM. IGNORE. 


An OCCURS clause is specified for an 91 
or 77 level data-name. The compiler 
ignores the OCCURS clause. 


-ACCEPT FROM. OBJECT NOT IN SPECIALNAMES. 
The mnemonic-name used in the ACCEPT 


statement was not defined in the 
SPECIAL-NAMES paragraph. Fatal. 
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ACCEPT IDENTIFIER INVALID. 


The word following the ACCEPT verb is 
not a data-name or is a data-name that 
has non-DISPLAY usage or invalid class. 
Fatal. 


VERB OR COND. CLAUSE CONFLICTS WITH FILE ACCESS. 
There is a conflict between the ACCES 
MODE of the referenced file and the I/O 


verbs and/or condition clauses that 
reference this file. Fatal. 


DATANAME AFTER .GO DEPENDING. INVALID. 


The word following the DEPENDING ON 
phrase of the GO TO statement is not a 
data-name or is a data-name that has 
INDEX uSage. Fatal. 


INVALID CLASS OF DATANAME AFTER .GO DEPENDING. 
The data-name following the DEPENDING ON 
phrase of the GO TO statement is not a 
numeric data-name or is a numeric, 
non-integer data-name. Fatal. 

-DISPLAY UPON. OBJECT NOT IN SPECIALNAMES. 
The mnemonic-name used in the DISPLAY 
statement was not defined in the 
SPECIAL-NAMES paragraph. Fatal. 

-DISPLAY. OPERAND IS INVALID. 


A data item in the DISPLAY statement has 
invalid class or USAGE. 


MISSING OR INVALID OPERAND FOR ARITHMETIC VERB. 
One of the operands of an arithmetic 
statement is either missing or invalid. 
Fatal. 

MISSING OR INVALID SOURCE OPERAND. 


The source operand is missing following 
an arithmetic verb. Fatal. 


MISSING OR INVALID DESTINATION OPERAND. 


-GIVING. REQUIRED AFTER .DIV...BY. 


The GIVING phrase INTO is missing in a 
DIVIDE...BY statement. Fatal. 
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-GIVING. REQUIRED AFTER LITERAL OPERAND. 


The GIVING phrase is required if the 
second operand of an ADD, DIVIDE, 
MULTIPLY, or SUBTRACT statement is a 
literal. Fatal. 


~-BY. MISSING IN .MULTIPLY. 


The keyword BY is missing in a MULTIPLY 
Statement. Fatal. 


-BY. OR .INTO. MISSING FROM .DIVIDE. 


One of the keywords BY or INTO is 
missing from the DIVIDE statement. 
Fatal. 


-FROM. MISSING IN .SUBTRACT. 


The keyword FROM is missing from. the 
SUBTRACT statement. Fatal. 


FILE NEEDS DYNAMIC ACCESS FOR .READ NEXT.. 


In a READ NEXT statement, the referenced 
file must have ACCESS MODE IS DYNAMIC 
specified in the FILE-CONTROL paragraph. 
Fatal. 


BAD PROCEDURE NAME IN .PERFORM.. 


A missing or invalid procedure name is 
recognized in the PERFORM statement. 
Fatal. 


ILLEGAL OPERAND OF .TIMES. OPTION OF .PERFORM.. 


The TIMES operand of the PERFORM 
statement is not a numeric integer 
data-name or numeric integer literal. 
The compiler assumes a value of 1 for 
the TIMES operand. 


-TIMES. MISSING FROM .PERFORM.. ASSUMED. 


The PERFORM statement does not contain 
the keyword TIMES but does contain the 
iteration value required to execute the 
PERFORM correctly. The keyword TIMES is 
assumed present. 


PROCEDURE NAME OMITTED IN .ALTER.. 


A valid procedure-name was not 
recognized in the ALTER statement. 
Fatal. 
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ILLEGAL .ALTER. DUE TO MISSING .TO.. 


The keyword TO was not recognized in the 
ALTER statement. Fatal. 


FILE HAS VAR. SIZE RECS. .READ INTO. ILLEGAL. 


It is illegal for the READ INTO 
statement to reference a file that has 
multiple record descriptions of 
different lengths. Fatal. 


FILE ACCESSED BY VERB REQUIRING .LINAGE. 


A file that did not have a LINAGE clause 
in its specification is accessed by an 
I/O verb. Fatal. 


-DELETE. OR .REWRITE. WITHOUT INV. KEY OR USE. 


A DELETE or REWRITE statement without 
the INVALID KEY phrase references a file 
for which there is no USE _ procedure. 
Fatal. 


OPEN MODE OR NO READ PROHIBITS REWRITE OR DELETE. 


A DELETE or REWRITE statement references 
a file that was not OPENed in the proper 
mode or that has no READ statement 
referencing it in the program. Fatal. 


-START. CONFLICTS WITH OPEN MODE. 


A START statement references a file that 
was not opened in the proper mode. 
Fatal. 


-WRITE. CONFLICTS WITH OPEN MODE. 


A WRITE statement references a file that 
waS not opened in the proper mode. 
Fatal. 


~READ. CONFLICTS WITH OPEN MODE. 


A READ statement references a file that 
is only opened in OUTPUT or EXTEND mode. 
Fatal. 


USE NOT IN DECLAR. OR NOT FOLLOWING SECTION NAME. 


The USE statement is not in the 
DECLARATIVES section of the PROCEDURE 
DIVISION or is not immediately following 
a section name inside the DECLARATIVES. 
Fatal. 
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MORE THAN 255 ALTERNATE KEYS. IGNORED. 


INTEGER IN SWITCH CLAUSE 


The maximum of 255 ALTERNATE KEYS has 
been exceeded. The clause is ignored. 


INVALID OR OMITTED. 


A SWITCH clause of the SPECIAL-NAMES 
paragraph either contains an invalid 
numeric integer or has omitted the 
integer in its specification. A SWITCH 
clause integer must be in the decimal 
range 1<=n<=16. The SWITCH clause is 
ignored. 


-IS. OMITTED IN SPECIALNAMES. ASSUMED PRESENT. 


The required keyword IS is omitted in a 
clause of the SPECIAL-NAMES paragraph. 
IS is assumed present and processing 
continues. 


DEVICE MNEMONIC OMITTED IN SPECIALNAMES. 


A valid device mnemonic-name is not 
recognized in one of the CONSOLE, 
LINE-PRINTER, CARD-READER, 
PAPER-TAPE-READER, or PAPER-TAPE-PUNCH 
clauses of the SPECIAL-NAMES paragraph. 
All source text is skipped until the 
next recognizable keyword. 


TERMINATOR OMITTED IN SPECIALNAMES. 


The SPECIAL-NAMES paragraph is not 
terminated by a period. The period is 
assumed present and processing 
continues. 


SUBJECT OF .ALTER. NOT .GO TO.. ALTER IGNORED. 


The paragraph referenced by an ALTER 
Statement does not contain a GO TO 
statement as its first statement. The 
ALTER: statement is ignored. 


KEYWORD OMITTED IN .SWITCH. CLAUSE. 


One of the keywords OFF or ON is omitted 
in the SWITCH clause of the 
SPECIAL-NAMES paragraph. The SWITCH 
clause is ignored. 


CONDITION NAME MISSING IN .SWITCH. CLAUSE. 


A valid condition-name is not recognized 
in the SWITCH clause of the 
SPECIAL-NAMES paragraph. The SWITCH 
clause is ignored. 
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752 .CR. OR .DB. NOT AT RIGHT END OF PICTURE. 


The PICTURE symbol CR or DB does not 
appear at the right end of the PICTURE 
string. The compiler ignores the 
user-supplied PICTURE and treats’ the 
data item as alphanumeric with a 
"PICTURE X" DECLARATION. 


Both the PICTURE symbols, CR or DB, and 
a sign, + or -, appear in the same 
PICTURE. The compiler ignores the 
user-supplied PICTURE and treats’ the 
data item as alphanumeric with a 
"PICTURE X" declaration. 


754 MULTIPLE DEFINITION OF SWITCH. FIRST USED. 
Multiple definitions of a COBOL switch 
are detected in the SPECIAL-NAMES 
paragraph. All but the first definition 
of SWITCH are ignored. 

755 .SENTENCE. ASSUMED AFTER .NEXT. 
The keyword NEXT is not followed by the 
keyword SENTENCE. SENTENCE is assumed 
present and processing continues. 

756 SUBSCRIPT NOT NUMERIC INTEGER. 
A data-name used aS a Subscript is not 
numeric in class. A default value of 1 
is assumed as the subscript. 

76@ ILLEGAL SYNTAX IN .DIVIDE. STATEMENT. 


The compiler detects illegal syntax in 
the DIVIDE statement. Fatal. 


761 INDEXED FILE REQUIRES .RECORD KEY. PHRASE. 
Self explanatory. 
762 RECORD KEY INVALID FOR THIS FILE. 


The RECORD KEY clause is valid only for 
indexed files. 


763  .ALT RECORD KEY. INVALID FOR FILE. IGNORED. 


The ALTERNATE RECORD KEY clause is valid 
only for indexed files. 


764  READ-AHEAD. OR. WRITE-BEHIND. NOT SUPPORTED. 
The APPLY READ-AHEAD and APPLY 
WRITE-BEHIND clauses are not supported 


in this version of the compiler. The 
APPLY clause is ignored. 
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765 INTEGER INVALID IN. RESERVE AREA. CLAUSE. 


The number of buffer areas reserved by 
the RESERVE clause is invalid. The 
clause is ignored, and a default of one 
area for SEQUENTIAL and RELATIVE or two 
areas for INDEXED is supplied. 


766 BAD VALUE IN BLOCK CONTAINS CLAUSE. 


The numeric literal in the BLOCK clause 
is less than the sum of the record size, 
the record header size, and the bucket 
header size. The BLOCK CONTAINS clause 
is ignored. 


767 VALUE IN. BLOCK CONTAINS. CLAUSE IS ROUNDED UP. 


The numeric literal in the BLOCK clause 
is not a multiple of 512. The value is 
rounded up to the next even multiple of 
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778 EXPECTED .RECORD KEY. DATANAME NOT DEFINED. 


The data-~name in a RECORD KEY clause has 
not been defined in the DATA DIVISION. 


‘771 + RECORD KEY. DATANAME HAS INVALID CLASS. 


A data-name referenced in a RECORD KEY 


or ALTERNATE RECORD KEY phrase of a 
SELECT clause in the FILE-CONTROL 


paragraph is defined with 
non-alphanumeric class in the FILE 
SECTION. 


772  .RECORD KEY. DATA ITEM CANNOT BE VARIABLE LENGTH. 


A data-name referenced in a RECORD KEY 
or ALTERNATE RECORD KEY phrase of a 
SELECT clause in the FILE-CONTROL 
paragraph is defined in the FILE SECTION 
as an item whose size is variable. 


773  .RECORD KEY. ITEM NOT DEFINED IN RECORD OF FILE. 


A data-name referenced in a RECORD KEY 
or an ALTERNATE RECORD KEY phrase of a 
SELECT clause is not defined in the 
record description of the associated 
file. 


774 FILE ACCESSED BY VERB REQUIRING INDEXED ORG. 


A file whose organization is SEQUENTIAL 
Or RELATIVE is referenced by the READ 
verb that has the KEY IS data-name 
phrase specified. The referenced file 
must have INDEXED organization. Fatal. 
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775 .KEY IS. PHRASE INVALID FOR SEQUENTIAL .READ. 


Either the file has ACCESS SEQUENTIAL or 
the READ statement contains the word 
NEXT. In either case the KEY Is 
data-name phrase is illegal. Fatal. 


776 INVALID DATANAME IN .KEY IS. PHRASE. 
The KEY IS phrase of the READ statement 
was not followed by a data-name. Fatal. 


777 KEY IS. PHRASE NOT FOLLOWED BY RECORD KEY. 


The data-name following the KEY Is 
phrase of the READ statement is not a 
RECORD KEY or ALTERNATE RECORD KEY for 
the referenced file. The RECORD KEY 
data-name is assumed. 


199% VARIABLE OCCURRENCES TABLE MUST END RECORD. 


A COBOL table declared with the 
DEPENDING ON phrase can be followed in 
the record only by data description 
entries whose level-numbers are greater 
than the level-number of this table 
entry. The compiler ignores the 
remainder of the record descriptor from 
the point where the error is detected. 
Fatal. 


1991 .ASCENDING. OR .DESCENDING. DATANAME EXPECTED. 


A user-defined data-name was expected, 
but not found, in the ASCENDING KEY IS 
or DESCENDING KEY IS phrase. 


1ff2 RENAMED DATAITEMS NOT IN CURRENT RECORD. 


The data items specified after the 
RENAMES keyword (that is, the data items 
being renamed) are defined outside of 
the current record description. The 
compiler ignores the entire RENAMES data 
description entry. 


1883 MAXIMUM OCCURRENCES NOT GREATER THAN MINIMUM. 


In a variable occurrence table 
declaration tha intanar fai lowing thea 


decl tion, the integer follo the 
keyword TO (that is, the maximum) must 
be greater than the integer following 
the keyword OCCURS (that is, the 
minimum) . The compiler assumes’ the 
maximum value to be one greater than the 
Minimum value. 
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IS OMITTED 


IN THE .OCCURS. CLAUSE. 


In a variable occurrence table 
declaration, the keyword DEPENDING has 
been omitted. The compiler ignores’ the 
remainder of the OCCURS clause and 
treats the table declaration as an 
ordinary COBOL table. 


19g5 A DATANAME MUST FOLLOW THE .DEPENDING. KEYWORD. 


In a variable occurrence table 
declaration, a valid data-name is not 
found following the keyword 


DEPENDING. The compiler ignores’ the 
remainder of the OCCURS clause and 
treats the table declaration as an 
ordinary COBOL table. 


The compiler detects a table San Ses 
with a DEPENDING ON phrase subordinat 

to a group item that has an OCCURS 
clause. The compiler ignores’ the 


DEPENDING ON phrase and treats the 
declaration as an ordinary COBOL table. 


1997 MAXIMUM NO. TABLE OCCURRENCES MUST BE POSITIVE. 


In a variable occurrence table 
declaration, the integer following the 
keyword TO (that is, the maximum) must 
be greater than zero. The compiler 
assumes the maximum value to be one 
greater than the integer value following 
the keyword OCCURS (that is, the 
minimum). 


1g1f EXPECTED .DEPENDING ON. DATANAME NOT DEFINED. 


The data-name referenced in a DEPENDING 
ON phrase was not defined in the DATA 
DIVISION. Fatal. 


1f11 EXPECTED .ASCENDING KEY. DATANAME NOT DEFINED. 


The data-name referenced in an ASCENDING 
KEY phrase was not defined in the DATA 
DIVISION. Fatal. 


1f12 EXPECTED .DESCENDING KEY. DATANAME NOT DEFINED. 


The data-name referenced in a DESCENDING 
KEY phrase was not defined in the DATA 
DIVISION. Fatal. 
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-DEPENDING ON. DATANAME NOT A NUMERIC INTEGER. 


The data-name referenced in a DEPENDING 
ON phrase was not declared as a numeric 
integer in the DATA DIVISION. Fatal. 


-RENAMES. APPLIED TO AN INVALID LEVEL OF DATA. 


The RENAMES clause specifies the 
renamin cof data items whose level 
number is $1, 66, 77, or 88. The 
compiler ignores the entire RENAMES data 
description entry. 


-DEPENDING ON. DATANAME DETECTED WITHIN TABLE. 


The compiler detects a data-name, that 
follows a DEPENDING ON phrase and that 
defines the current number of 
occurrences in a variable occurrence 
table, to have its storage allocated 
within the range of the table. Fatal. 


-OCCURS. CLAUSE ON A TABLE KEY DATANAME. 


The compiler detects the presence of an 
OCCURS clause on a data item that has 
been declared as an ASCENDING or 
DESCENDING KEY. Fatal. 


-SEARCH ALL. TABLE DOES NOT HAVE KEYS. 


The table being searched by a SEARCH ALL 
statement must have the ASCENDING KEY or 
DESCENDING KEY phrase specified in its 
declaration. Fatal. 


IMPERATIVE STATEMENT EXPECTED DURING .SEARCH. 


A period or a non-imperative statement 
was found where the SEARCH statement 
environment is expecting an imperative 
statement. Fatal. 


KEYS SPECIFIED FOR .SEARCH ALL. NOT DENSE. 
When a key is referenced for the SEARCH 
ALL statement, all preceding keys in the 


KEY clause of the table declaration must 
also be referenced. Fatal. 


-WHEN. EXPECTED BUT NOT FOUND IN .SEARCH. 
The compiler expected but failed to 
recognize the WHEN keyword while 
compiling the SEARCH statement. Fatal. 
THE KEYWORD .WHEN. ILLEGAL IN THIS CONTEXT. 
The compiler detects the presence of the 


keyword WHEN outside the environment of 
the SEARCH statement. Fatal. 
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THE KEYWORD .SEARCH. ILLEGAL IN THIS CONTEXT. 


While compiling a SEARCH statement, the 
compiler detects the presence of another 
SEARCH statement. The second SEARCH 
statement is detected at a point where 
an imperative statement is expected. 
Fatal. 


KEY MUST BE SUBSCRIPTED BY FIRST INDEX OF TABLE. 


The SEARCH ALL statement requires’ that 
the key referenced on the left side of 
the simple condition must be subscripted 
by the first index name of the table 
being searched. Fatal. 


THE KEYWORD .SENTENCE. EXPECTED AFTER .NEXT.. 


The keyword SENTENCE was not detected 
after the NEXT keyword during’ the 
compilation of a SEARCH statement. 
Fatal. 


TABLE NAME NOT FOUND AFTER .SEARCH. VERB. 


The compiler failed to recognize a valid 
table data item after the keyword SEARCH 
Or SEARCH ALL. Fatal. 


INVALID TABLE REFERENCE IN .SEARCH. STATEMENT. 


The table data item reference following 
the SEARCH or SEARCH ALL verbs must have 
both the INDEXED BY and the OCCURS 
clauses specified in its 
declaration. Fatal. 


DATANAME EXPECTED AFTER .VARYING. IN .SEARCH. 


No data-name reference was found after 
the VARYING keyword in the SEARCH 
statement being compiled. Fatal. 


-VARYING. ITEM MUST BE INDEX OR INTEGER. 


The data-name reference following the 
VARYING keyword must be an index data 
item, an index-name, or an elementary, 
numeric, integer data-name reference. 
Fatal. 


-SEARCH ALL. DATA ITEM IS NOT A KEY. 


The data item referenced on the left 
side of the SEARCH ALL simple condition 
must be declared as an ASCENDING or 
DESCENDING KEY. Fatal. 
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1934 DATA ITEM NOT A KEY FOR THIS .SEARCH. TABLE. 


The data item referenced on the left 
side of the SEARCH ALL simple condition 
is not a key for the table being 
searched. Fatal. 


1935 .RENAMES. SPECIFIES RENAMING OF A COBOL TABLE. 


The RENAMES clause specifies the 
renaming of an item that has an OCCURS 
clause in its declaration Or is 
subordinate to another item having an 
OCCURS clause. The compiler ignores the 
entire RENAMES data description entry. 


1936 .RENAMES. APPLIED TO VARIABLE LENGTH DATAITEM. 


The compiler detects an application of 
the RENAMES clause to a range of data 
items that contains a data item whose 
length is variable at run-time because 
is has a subordinate data item whose 
data description entry contains an 
OCCURS DEPENDING ON clause. The 
compiler ignores the entire RENAMES data 
description entry. 


1937 DATANAME OMITTED AFTER 66 LEVEL NUMBER. 


The data-name declaration is omitted 
after a 66 level number. The compiler 
ignores the entire RENAMES data 
description entry. 


1948 .RENAMES. OMITTED IN LEVEL 66 DESCRIPTION ENTRY. 


The RENAMES keyword is omitted in a 
level 66 data description entry. The 
compiler ignores the entire level 66 
data description entry. 


1941 SEARCH KEY NOT SUBORDINATE TO TABLE. 


The compiler detects an ASCENDING or 
DESCENDING data-name key that is not 
defined as a data item subordinate to 
the associated SEARCH table. 


1942 INVALID OR MISSING DATANAME AFTER .RENAMES.. 


The data-name is missing after the 
RENAMES keyword or, if present, is not 
recognized as a valid data item that was 
previously defined. The compiler 
ignores the entire RENAMES data 
description entry. 
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ITEM NOT ALLOWED BETWEEN TABLE AND KEY. 


The compiler detects a . data item 
declared with an OCCURS clause 
"sandwiched" between the declaration of 
another COBOL table and its associated 
SEARCH key. 


1944 .RENAMES. SPECIFIES INVALID NOMENCLATURE RANGE. 


In processing the RENAMES clause, the 
compiler detects an invalid nomenclature 
range specified by identical data-names 
following the RENAMES and THRU keywords, 
respectively. The compiler ignores’ the 
entire RENAMES data description entry. 


1945 .RENAMES. SPECIFIES STORAGE OVERLAP ON LEFT END. 


In processing the RENAMES clause, the 
compiler detects the condition in which 
the beginning of the storage allocated 
to the data-name after the THRU keyword 
is to the left of the beginning of the 
storage allocated to the data-name after 
the RENAMES keyword. The compiier 
ignores the entire RENAMES data 
description entry. 


1946 INVALID OR MISSING DATANAME AFTER .THRU.. 


In specifying the RENAMES clause, a 
data-name is missing after the THRU 
keyword Or, if present, is not 
recognized as a valid data item that was 
previously defined. The compiler 
ignores the entire RENAMES data 
description entry. 


1947 DATANAME MISSING AFTER .CORRESPONDING. 


In the processing of an ADD, SUBTRACT, 
or MOVE CORRESPONDING statement, the 
compiler detects the omission of a valid 
data-name reference after the 
CORRESPONDING keyword. Fatal. 


1g5g .TO. OR .FROM. OMITTED IN .CORRESPONDING.. 


In the processing of an ADD, SUBTRACT, 
or MOVE CORRESPONDING statement, the 
compiler detects the omission of the TO 
Or FROM keyword. Fatal. 


1951 INVALID OR MISSING DATANAME AFTER .TO. OR .FROM. 


In the processing of an ADD, SUBTRACT, 
or MOVE CORRESPONDING statement, the 
compiler detects the omission of a valid 
data-name reference after the keyword TO 
or FROM. Fatal. 
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1952 NO OBJECT CODE PRODUCED FOR .CORRESPONDING. 


1953 


1954 


1g55 


1956 


1657 


1g6g 


-FILE STATUS. 


In the processing of an ADD, SUBTRACT, 
or MOVE CORRESPONDING statement, the 
compiler produced no object code because 
no "correspondence" was found between 
the two group items referenced in the 
COBOL statement containing the 
CORRESPONDING option. This diagnostic is 


: : 
informational only. 


GROUP ITEM NOT REFERENCED IN .CORRESPONDING. 


In the processing of an ADD, SUBTRACT, 
or MOVE CORRESPONDING statement, the 
compiler discovered that one of the 
references is a reference to an 
elementary item. Fatal. 


LEVEL 66 REFERENCE DISALLOWED IN .CORRESPONDING. 


In the processing of an ADD, SUBTRACT, 
or MOVE CORRESPONDING statement, the 
compiler detects a reference to a 
data-name declared at level 66. This is 
an invalid reference. Fatal. 


ITEM DEFINED IN .FILE SECTION. 


A data-name referenced in a FILE STATUS 
phrase of a SELECT clause is defined in 
the FILE SECTION of the COBOL 
program. The compiler ignores this error 
and continues to process the FILE STATUS 
data-name. 


INCOMPATIBLE OPERANDS FOUND IN .CORRESPONDING. 


In the processing of an ADD, SUBTRACT, 
or MOVE CORRESPONDING statement, the 
compiler detects a pair of CORRESPONDING 
data items that are incompatible. This 
diagnostic is informational only. 


EMPTY .GO TO. WAS NOT THE SUBJECT OF AN .ALTER.. 


A GO TO statement without a procedure 
reference was detected. The empty GO TO 
is not the subject of an ALTER 
statement. Fatal. 


QUALIFIER OMITTED IN PROCEDURE REFERENCE. 


A section name is omitted after the 
keyword OF Or IN in a qualified 
procedure reference of the COBOL 
statement being compiled. Fatal. 
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INCONSISTENT NUMBER OF ARGUMENTS IN .CALL.. 


The subprogram referenced in this CALL 
statement has been referenced before. 
The number of arguments in the earlier 
CALL differs from the number’ in the 
current CALL. 


PARAGRAPH WITHOUT SECTION PRECEDES THIS SECTION. 


DUPLICATE PARAGRAPH NAME 


In a COBOL program, if one paragraph is 
in a section, then all paragraphs must 
be in sections. In this Source program, 
a paragraph not within a section has 
been detected preceding this section in 
the source program. 


DETECTED. 


In a section of the Procedure Division, 
a paragraph name is defined more than 
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even with qualification. 


REFERENCE TO UNDEFINED PROCEDURE NAME. 


The compiler detects a reference to an 
undefined procedure name in the 
PROCEDURE DIVISION. 


UNDEFINED PROCEDURE QUALIFIER REFERENCE. 


The compiler detects a qualified 
procedure reference that contains an 
undefined qualifier in the PROCEDURE 
DIVISION. 


ILLEGAL PROCEDURE NAME REFERENCE. 


AMBIGUOUS PROCEDURE NAME 


The compiler detects an invalid 
procedure name reference in the 
PROCEDURE DIVISION. 


REFERENCE. 


The compiler detects a reference in the 
PROCEDURE DIVISION to a procedure name 
that is not uniquely referenceable, even 
through qualification. 


PARAGRAPH NAME DISALLOWED AS QUALIFIER. 


The compiler detects a qualified 
procedure reference in which the 
qualifier is a paragraph name. 


SECTION NAME REFERENCE MAY NOT BE QUALIFIED. 


The compiler detects a qualified 
procedure reference in which a section 
name is qualified by another section 
name. 
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AMBIGUOUS PARAGRAPH NAME 


POSSIBLE .PERFORM. RANGE 


REFERENCE. 


The compiler detects a reference in the 
PROCEDURE DIVISION to a paragraph name 
that is not uniquely referenceable, even 
through qualification. 


VIOLATION. 


The compiler detects a PERFORM THRU 
Statement in which the procedure name 
following THRU is defined before’ the 
procedure name following the PERFORM. 
This condition could a logic problem in 
the COBOL program being compiled. 


NUMERIC PROCEDURE NAME EXCEEDS 3f CHARACTERS. 


A numeric string that appears to be a 
numeric procedure name exceeds 39 
characters in length. The string is 
truncated on the right to 3f characters 
and processing of the numeric procedure 
name continues. 


NUMERIC PROCEDURE NAME CONTAINS DECIMAL POINT. 


A numeric string that appears to be a 
numeric procedure name contains a 
decimal point. The compiler ignores the 
presence of the decimal point and 
proceeds with the processing of the 
numeric procedure name. 


-RELATIVE KEY. ITEM DEFINED IN RECORD OF FILE. 


NO. OF AREAS DEFAULTS TO 


A data-name referenced in a RELATIVE KEY 
phrase of a SELECT clause is defined in 
the record description of the associated 
file. The compiler ignores this error 
and continues to process the RELATIVE 
KEY data-name. 


MAX. FOR FILE TYPE. 


The number of buffer areas reserved by 
the RESERVE clause is greater than the 
maximum allowed for the file 
organization. The compiler allocates 
two areas for a sequential file and one 


far a Pabeie £37 
ror a@ FeLtarcrive rise. 


UNRECOGNIZED LITERAL TYPE...SYSTEM ERROR 


The compiler has failed to properly 
identify a literal. System error. 
Fatal. 
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1197 .TO. OR .GIVING. MISSING IN ADD 


The keyword TO or GIVING was not found 
after the second operand in an ADD 
Statement. Fatal. 


1118 MORE THAN 18. DIGITS IN COMPOSITE. TRUNCATING. 
The length of an arithmetic composite is 
greater than 18 digits. The composite 


is truncated on the left to 18 digits. 
Warning. 


1111 ONLY ONE DEST ALLOWED AFTER .CORRESPONDING. USE FIRST. 
More than one destination data-name 
follows the keyword CORRESPONDING. The 
compiler ignores all but the first. 
Warning. 


1113 UNSIGNED COMP 3 ITEMS ILLEGAL 


The PICTURE for a COMP-3 item does not 
contain an S character. Fatal. 
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RECORD MANAGEMENT SERVICES ERROR CODES 


This appendix lists the RMS error codes that can be reported during 
COBOL program execution. These codes appear in conjunction with COBOL 
Object Time System error messages, which are described in Appendix J. 


The error codes appear in the form: 


CBL -- NN: (MESSAGE) 
ASSOCIATED RECORD SERVICES ERROR: -nn (mm) 


The NN portion of the CBL message is the COBOL OTS error code; 
(MESSAGE) is the message text, which provides a brief description of 
the error. 


The nn portion of the RMS message is one of the error codes’ listed 
below. 


The (mm) portion of the RMS message is displayed for I/O errors only. 
The (mm) error codes are listed in the: 


e IAS/RSX-11 I/O Operations Reference Manual (Appendix I). 
e RSTS/E Systems Manager's Guide (Appendix C). 


Most errors can occur in RSX-11M, IAS, and RSTS/E systems. 
System-specific errors are identified in the description. The term 
"file processor" refers to FIP {on RSTS/E systems) or FI11ACP (on 
RSX-11M and IAS systems). 


If you encounter an error code that is not listed, submit a Software 
Performance Report {SPR). 


~32 (mm) An OPEN statement in the program failed because’ the 
file processor could not access the file. 


-96 The program failed to create a new file because the 
allocation guantity specified in the /AL or /CO switch 
was too large. 


-112 (mm) The program failed to OPEN a file on an ANSI-labelled 
Magnetic tape because the records in the file were 
variable-length but not in ANSI D format. 


-169 


-176 


-394 


-329 


-336 


-368 


- 499 


-448 


-464 


(mm) 


(mm) 


(mm) 


(mm) 


(mm) 
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The file processor detected an error while reading the 
attributes of the file. 


The file processor detected an error while writing the 
attributes of a file. 


A REWRITE operation failed because: 


1. The value of the prime key field of the record to 


be wriktbtan hae nhanaed ar 
vy WELLLLTL HAS CliGaNYyYoTU UL, 


2. The value of an ALTERNATE key field has changed 
but the change attribute was not specified for the 
key when the file was created. 


NOTE 


The second condition can occur only if the 
file was not created by a COBOL program, 
since all alternate keys are changeable 
according to the 1974 ANSI COBOL standard. 


The program failed to perform a record operation 
because RMS detected an index bucket format check-byte 
failure. The bucket has been corrupted and random 
access to one. or more records is affected. Use the 
RMS DEFINE and CONVERT utilities to correct the file 
or use a backup copy of the file to restore it. 


The program failed to CLOSE a file on magnetic tape 
because the RSTS/E CLOSE failed to access the magnetic 
tape unit specified in the program's ASSIGN or VALUE 
OF ID clause. This error can occur only on RSTS/E 
systems. 


The program failed to OPEN a file for OUTPUT because 
the file processor could not create the file. 


The program failed to CLOSE a file because the file 
processor could not deaccess the file. 


The program failed to OPEN a file because it specified 
an invalid or inappropriate device. Assigning the 
file to a non-existent device or assigning an indexed 
file to a magnetic tape device could cause this error 
to be reported. 


The program failed to OPEN a file because a syntax 
error appears in the directory portion of the file 
specification. Check the VALUE OF ID an SELECT 
clause for the file. 


-489 


-496 


=o l2 


-52¢9 


-569 


-576 


-592 


-616 


-624 


~672 


-794 


(mm) 


(mm) 


(mm) 
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The program failed to OPEN the file because there is 
insufficient buffer space for RMS to allocate either 
I/O buffers or control structures to support file 
processing. This can occur, for example, if the 
actual bucket size for a relative or indexed file is 
larger than the bucket size implied by the program's 
BLOCK CONTAINS clause and/or record descriptions. Use 
the RMS DISPLAY utility to determine the actual size 
of the buckets in the file. 


The program failed to OPEN the file because the 
directory in the file-spec specified in either the 
VALUE OF ID or SELECT clause cannot be found. 


The program failed to OPEN a file because the 
specified device was not ready. 


The program failed to OPEN the file because the file 
processor detected a device positioning error. This 
is a transient hardware error; however, if it 
persists, contact your Digital field service 
representative. 

The program failed to perform a WRITE or REWRITE 
operation because the operation would cause 
duplication in the file of one or more alternate keys 
that do not have the WITH DUPLICATES attribute. 


The program failed to OPEN a file because the file 
processor could not insert the file directory entry. 


The program failed for one of the following reasons: 


1. An OPEN operation has failed because the 
Organization of the file being opened was not 
correctly specified in the file's SELECT clause. 


2. A record operation has failed because it is 
inconsistent with the OPEN mode of the file. For 
example, this error would be reported if the 
program executed a WRITE statement for a file 
Opened for INPUT. 


The program detected end-of-file on a file that it was 
processing. 


The program failed to OPEN a magnetic tape file for 
OUTPUT because the expiration date has not _ been 
reached. Character positions 48-53 of the file-header 
label (HDR1) contain the expiration date. 


The program failed to perform a WRITE or REWRITE 


operation because the file processor could not extend 


the file. 


The program failed to create (that is, OPEN for 


OUTPUT) a file because the specified file already 


exists. 


The program was not able to access a file because’ the 
file was locked by another user. 
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-726 The program failed to OPEN a file because the file 
processor could not locate the specified file 
directory entry. 


-736 The program failed to OPEN a file because it does not 
exist. 
-752 The program failed to OPEN a file because a_=e syntax 


error was detected in the file-name portion of the 


file specification obtained from the ASSIGN or SELECT 
clause of the program. 


-784 The program was not able to create (i.e., OPEN for 
OUTPUT) or extend (as part of WRITE or REWRITE 
operation) a file because the recording medium is 
full. 


-889 The program attempted to perform an operation that is 
not allowed for the file organization. For example, 
deleting a record from a seguential file. 


-896 The program failed to perform a READ, WRITE, or 
REWRITE operation because a record with an invalid 
count field was detected in a sequential file. 


-969 The program failed to perform a READ or START 
operation because the specified data item does not 
represent a key that is defined for the file. 


~1998 The program failed to OPEN a file on magnetic’ tape 
because the tape volume was not in ANSI format. 


-1924 The program failed to perform the specified operation 
because the file processor detected a busy channel. 


-1194 The program failed to perform a random record 
operation ona relative file because the value in the 
RELATIVE KEY data item exceeds the maximum record 
number specified when the file was created. 


NOTE 


This condition can occur only if the file was 
not created by a COBOL program (for example, 
the file was created by the RMS DEFINE utility 
which permits specification of a maximum 
record number). 


~1152 The program failed to perform a WRITE operation to a 
sequential file because the file was not positioned at 
EOF. 


-1168 


-1299 


-1248 


-1296 


=1392 


-1449 


-1456 


-1472 


-1488 


-152¢ 


-~1568 


(mm) 


(mm) 


(mm) 


(816) 


(mm) 
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The program failed to OPEN a file because the SELECT 
clause in the program did not specify the same number 
of alternate record keys that were specified when’ the 
file was created. Therefore, insufficient buffer 
space is available in the task for the allocation by 
RMS of internal control structures known as index 
descriptors. 


The program failed to OPEN a file because the RSTS/E 
OPEN function could not access the magnetic tape unit 
specified in the ASSIGN and/or SELECT clause. This 
error occurs only on RSTS/E systems. 


The program failed to perform the specified operation 
because an error was detected in the file's prologue. 
The file may be corrupted. Use the RMS DEFINE and 
CONVERT utilities to recreate and reload the file, or 
use a backup copy of the file to restore it. 


The program failed to OPEN a file because the program 
does not have the proper privilege authority to access 
the file. 


The program failed to OPEN a file because the file 
processor detected a read error. 


The program failed to perform a WRITE operation to a 
relative file because a record already exists in the 
target record position. 


The program failed to perform the specified operation 
to a relative or indexed file because the target 
bucket was locked by another user. 


The program failed to CLOSE a file because the 
RSX-F11ACP REMOVE function could not delete the 
directory entry. This error occurs only on _ RSX-11M 
and IAS systems. 


The program failed to perform a READ, START, DELETE, 
Or REWRITE operation to a relative or indexed file 
because the record specified in the random access 
Operation does not exist. When an (mm) code of -816 
also appears in the RMS error message, it further 
indicates that the operation is to an indexed file and 
that the file is empty. 


The program failed because it tried to UNLOCK a 
bucket (record) that was not LOCKED. 


The program failed because RMS detected a file 
Processor error. An error was detected while reading 
the file prologue, and the file may be corrupted. Use 
the RMS DEFINE and CONVERT utilities to recreate and 
reload the file, or use a backup copy of the file _ to 
restore it. 


The program failed because: 
1. The size of the record to be written by a WRITE or 


REWRITE operation exceeds the maximum record size 
specified when the file was created, or 


-1584 


-1699 


-1616 


-1664 


-1689 


-1696 


-1744 


(mm) 


(mm) 
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2. The size of the record in a REWRITE operation to a 
sequential file does not egual the size of the 
original record. 


The program failed to READ a _ record because the 
program does not have a buffer large enough for the 
record. Either the record descriptions or the BLOCK 
CONTAINS clause are inconsistent with the actual size 
of the records in the file. Use the RMS DISPLAY 


file's records. 


The program failed to perform a WRITE or REWRITE 
operation to an indexed file in sequential access mode 
becuase the prime key of the record is not greater 
than the key of the last accessed record. 


The program failed to OPEN a file because the file is 
sequentially organized and cannot be shared with 
another user. This error could be reported if the 
program specifies the /SH switch in the ASSIGN or 
VALUE OF ID clause for the file. 


The program failed to OPEN or CLOSE a file because a 
system directive error occured. 


The program failed to perform a record 
operation (READ, WRITE, REWRITE, UPDATE or DELETE) to 
an indexed file. The file is corrupted. Use the RMS 
DEFINE and CONVERT utilities to recreate and reload 
the file, or use a backup copy of the file to restore 
its 


The program failed to OPEN a file because a syntax 
error was detected in the file type portion of the 
file specification obtained from the SELECT and VALUE 
OF ID clauses. 


The program failed to OPEN a file because a _ syntax 
error exists in the version number portion of the file 
specification obtained from the VALUE OF ID and SELECT 
clauses. This error can occur only on RSX=11M and IAS 
systems. 


The program failed to CLOSE a file because the file 
processor detected a write error. 


The program failed to OPEN a file because the 
recording medium is write-locked. For magnetic tapes, 
insert a write-ring; for disk-drives, move the 
write-lock switch to the off position. 


An error has occurred during an RMS write operation to 
the file's prologue. The file may be corrupted. Use 
the RMS DEFINE and CONVERT utilities to correct the 
file, or use a backup copy of the file to restore it. 


APPENDIX J 


OBJECT-TIME SYSTEM ERROR MESSAGES 


This appendix lists and describes the COBOL Object-Time System error 
messages. The run-time system. displays these messages when it detects 
errors during the execution of COBOL tasks. 


In some cases, the OTS displays an additional line containing an 
associated Record Management Services error code that further 
specifies the error condition. RMS error codes appear in Appendix I. 


NOTE 


Error codes that are preceded by an 
asterisk (*) indicate fault conditions 
during task execution. They are 
described in the documentation set for 
your operating system. 


These fault conditions could result from 
COBOL program errors, such as: 


@ a "run-away" subscript or index in a 
program compiled with the /-BOU 
switch 


e usSing CID in a program compiled with 
the /RO switch 


1: SUBSCRIPT TOO SMALL OR TOO LARGE 


The subscript value for a data item is 
not greater than zero, or it is greater 
than the maximum number of occurrences 
of the table data item. 


2: INDEX TOO SMALL OR TOO LARGE 


The value of an index-name is not 
greater than zero, or it is greater than 
the maximum number of occurrences of the 
table data item. 
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3: DEPENDING ON ITEM TOO LARGE OR TOO SMALL 


The value of the data item that defines 
the size of the table is not in the 
table size range specified in the OCCURS 
clause. 


4: ILLEGAL PROGRAM REENTRY 


A COBCL subprogram attempted to call 
itself, either directly or indirectly. 
The EXIT PROGRAM statement must be 
executed in a subprogram before’ the 
subprogram can be called again. 


5: INCORRECT NUMBER OF ARGUMENTS 


The number of arguments received by a 
COBOL subprogram does not agree with the 
expected number of arguments; that is, 
the number of CALL statement arguments 
in the calling program is not the same 
as the number of arguments in the 
PROCEDURE DIVISION USING phrase of the 
called program. 


6: PERFORM STACK OVERFLOW 


The number of nested PERFORMS. has 
exceeded the maximum; the maximum is 
either the default (ten) or the number 
specified by the value of the /PFM:n 
compiler switch. 


7: PERFORM END OF RANGE VIOLATION 


The program reached the end of an active 
PERFORM while processing a more-recently 
executed PERFORM; that is, the program 
executed a PERFORM statement whose range 
overlaps’ the end of the PERFORM 
statement that is currently being 
executed. 


8: ILLEGAL NESTED PERFORM 


The program attempted to execute a 
PERFORM statement whose exit is also the 
exit of a previously executed PERFORM 
that is still active. 


9: NULL ALTERABLE GO TO 
The program reached an alterable GO TO 
statement before assigning it a 
procedure name. 
1g: SAME AREA ALREADY BUSY WHEN OPENING 
The program tried to OPEN a file that 


uses the same buffer area as another 
open file. 


J-2 
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11: FILE ALREADY OPEN 


12: FILE NOT OPEN 


13: 


14: 


15: FILE PREVIOUSLY LOCKED 


16: 


17: OPEN ERROR 


18: CLOSE ERROR 


READ MUST PRECEDE REWRITE OR 


The program tried to OPEN a file that is 
currently open. 


otherwise 
not currently 


The program tried to CLOSE or 
access a file that is 
open. 


INVALID OPERATION ATTEMPTED 


The program tried to execute one of the 
following I/O statements for a file that 
is open in an incompatible mode: 


(a) 
(b) 


a READ for a file open for OUTPUT 
a WRITE for a file open for INPUT 
consistent 


(for 
sequential 


(c) an I/6d not 
with the 
example, 


file) 


operation 
file organiz 
START on a 


DELETE 


The program attempted to execute a 
REWRITE or DELETE statement for a 
sequentially accessed file, but the last 
I/O operation on the file was not a 
READ. 


file for 
executed a 


The program tried to access a 
which it had previously 
CLOSE...WITH LOCK statement. 


CLOSING UNIT OR REEL UNSUCCESSFUL 


The program executed a CLOSE UNIT or 
CLOSE REEL statement that failed. The 
accompanying RMS error code further 
specifies the error. 


The execution of an OPEN statement 
failed. The accompanying RMS error code 
further specifies the error. 


The execution of a CLOSE statement 
failed. The accompanying RMS error code 
further specifies the error. 


19: 


20: 


21 


22: 


23: 


24: 


25: 


RS 
oO 
ee 


27: 


28: 


OBJECT- TIME 


NOT OPEN FOR OPERATION 


INVALID LINAGE VALUE 


SYSTEM ERROR MESSAGES 


The program tried to execute an I/O 
statement for a file that is not open. 


The LINAGE clause specifies a page body 
size that results in an invalid value; 
the value is not greater than zero, or 
it is out of range. 


NO END OF FILE PROCESSING 


READ ERROR 


WRITE ERROR 


REWRITE ERROR 


DELETE ERROR 


START ERROR 


UNLOCK ERROR 


BAD NAME USING file-name 


An end-of-file has been detected, but 
the I/O statement does not have an AT 
END clause, and the program has no USE 
procedure for end-of-file processing. 


The execution of a READ statement 
failed. The accompanying RMS error code 
further specifies the error. 


The execution of a WRITE statement 
failed. The accompanying RMS error code 
further specifies the error. 


The execution of a REWRITE statement 
failed. The accompanying RMS error code 
further specifies the error. 


The execution of a DELETE statement 
failed. The accompanying RMS error code 
further specifies the error. 


The execution of a START statement 
failed. The accompanying RMS error code 
further specifies the error. 


An unsuccessful attempt has been made to 
uniock a record in the file. The 
accompanying RMS error. code further 
specifies the error. 


The file specification or associated 
switches for a file description are 
syntactically incorrect. 


29: 


31: 


Ww 
bo 
ee 


re a 2 


34: 


Sos 


36: 


OBJECT-TIME SYSTEM ERROR MESSAGES 


STOP 


UNKNOWN PROCEDURE 


ACCEPT ERROR 


Not an error. The program executed a 
STOP literal statement. Enter a 
carriage return to continue program 
execution. 


The program attempted to transfer 
control to an undefined procedure-name; 
a fatal diagnostic error message was 
issued at compile time. The program was 
compiled with the /ACC:2 switch. See 
compiler source program listing. 


The program failed to ACCEPT data from 
the user. The input device is busy, 
off-line, or otherwise unavailable. 


The program failed to DISPLAY data to 
the user. The output device is busy, 
off-line, or otherwise unavailable. 


UNABLE TO COMMUNICATE WITH USER 


The run-time system failed to display an 
error message to the user. This error 
is not displayed, but its code is 
returned as the exit status. 


FATAL SOURCE ERROR ENCOUNTERED 


ENVIRONMENTAL INTEGRITY 


The run-time system tried to execute a 
part of the program that contains fatal 
errors. The program was compiled with 
the /ACC:2 switch. See compiler source 
program listing. 


FAULT 


Part of the run-time system has_ been 
damaged by the COBOL program or by an 
error in the run-time system itself. 
This error could result from a 
"run-away" subscript or index in 
programs compiled with the /-BOU switch. 


SPECIFY ALL "ON" SWITCHES 


Not an error. This message appears when 


program execution begins if the 
SPECIAL-NAMES paragraph contains a 
SWITCH ON or OFF statement. (See 
Section 2.6.2, Setting Program 


Switches.) 


38: 
39: 


4l: 
42: 
43: 
44; 


45: 


46: 
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INVALID INPUT, TRY AGAIN 
The user incorrectly responded to. the 
SPECIFY ALL "ON" SWITCHES message. {See 
Section 2.6.2, Setting Program 
Switches.) 

ODD ADDRESS FAULT 

MEMORY PROTECTION VIOLATION 

BPT INSTRUCTION 

IOT INSTRUCTION 

RESERVED INSTRUCTION 

INVALID EMT INSTRUCTION 

FLOATING POINT EXCEPTION 

PERFORM COUNT TOO LARGE 
The value of the iteration counter’ used 
in a PERFORM procedure identifier TIMES 
statement exceeded the limit, which is 
32767. 

EXPONENT TOO LARGE OR TOO SMALL 
The exponent used in a COMPUTE statement 


is out of range. The legal range is 
-32768 to 32767. 


INDEX 


Abbreviated ODL file, 2-19 
Abortive diagnostic, 12-4 
/ACCin switch, 2-12, 2-15, 12-4 
ACCEPT statement, 6-39, 6-45 
Access method, 6-1 
ACCESS MODE clause, 6-19, 6-32 
Access modes, 6-19 
Accumulation of storage overhead, 
14-9 
Active/Inactive arguments, 3-41 
ADD statement, 4-19 
multiple operands, 4-18 
Addressing, 
CID, 13-3 
ADVANCING clause, 6-6 
/AL:n switch, 14-4, 14-11 
Alignment of data, 3-3 
ALL literal, 3-26 
Alphabetic data, 3-1 
Alphanumeric data, 3-1 
ALTER statement, 7-5 
Alternate key, 6-24 
Alternate key index, 14-7 
Argument, 
Replacement, 
Tally, 3-44 
Argument address list, 19-6 
Argument list, 
Tally, «3-45 
Argument match, 
INSPECT, 3-42 
Arguments, 
Subprogram, 19-3 
Arithmetic expression processing, 
4-22 
Arithmetic statements, 
common errors, 4-21 
ASCENDING/DESCENDING KEY attributes, 
5-17 
ASCII character set, 3-3 
ASCII codes, 3-4 
ASSIGN clause, 6-43 
Assumed decimal point, 4-6 
AT END condition, 12-4 


3-52 


4-15 


BEFORE/AFTER phrase, 3-37, 3-41, 
3-51 
Binary format, 4-1 
Binary search of table, 5-17 
Blank insertion, 3-19 
Block, 
logical, 6-6, 6-15, 6-27 
Virtual, 6-6, 6-15, 6-27 
BLOCK CONTAINS clause, 6-6, 
6-28, 14-8 
Blocking factor, 6-8, 6-39 
Blocking of records, 6-15 
/-BOU switch, 2-12, 14-19 
Breakpoints in CID, 13-9 
Bucket, 6-15, 6-27, 14-5 


6-15, 


Bucket pointer, 14-7 
Bucket size, 
Effect of, 6-15 
Selecting, 14-8 
Bucket split, 14-7 
Buffer size, 6-8, 
Buffer space, 6-31 
Buffering, 6-7, 6-17, 6-39 


6-18, 6-39 


Caching index roots, 14-3 
Calculating bucket size, 6-17, 6-28 
Calculating buffer space, 6-8, 6-18, 
6-31 
CALL statement, 19-1, 19-2, E-1l 
Calling a subprogram, 19-2 
Calling MACRO programs, 19-4 
CANCEL BREAKPOINT, 
CID command, 13-5 
Card reader, 6-39 
Characteristics of devices, 6-38 
Characters, 
Special, 3-3 
Choosing data types, 14-19 
CID, 2-19, i3-1 
breakpoints in, 13-9 
command errors in, 13-19 
examples, 13-11 
program initiation, 13-8 
program suspension, 13-9 
program termination, 13-9 
CID addressing, 13-3 
CID command, 13-4 
CANCEL BREAKPOINT, 13-5 
DEPOSIT, 13-5, 13-6 
EXAMINE, 13-6 
GO, 13-7 
SET BREAKPOINT, 13-7 
SHOW BREAKPOINTS, 13-8 
XIT, 13-8 
CID command mode, 13-2 
CID environment, 13-2 
/CL:n switch, 14-11 
Class, 
on source listing, G-3 
Class tests, 4-19 
Data, 3-6 
Classes of data, 3-5 
CLOSE REEL clause, 6-39 
CLOSE statement, 6-13, 6-24, 6-37 
Closing indexed files, 6-37 
Closing relative files, 6-24 
/CM6 switch, 2-13 
/CO:n switch, 14-4, 14-12 
COBOL file types, 6-2 
COBOL Interactive Debugger, 13-1 
Codes, 
Device, 6-37 
Collating sequence, 3-6 
Command, 
CID, 13-4 


Index-1 


INDEX (Continued) 


Command line, 
compiler, 2-19, 
Command mode, 
CID, 13-2 
Common errors, 
arithmetic statements, 
INSPECT statement, 3-55 
library facility, 2-8 
MOVE statement, 3-12 
numeric moves, 4-14 
STRING statement, 3-29 
UNSTRING statement, 3-36 
Communication with the program, 6-45 
Comparison operation, 3-6 
Compatibility, 6-47 
Compilation, 2-9 
identification number, G-1 
multiple program, 2-19 
Single program, 2-9 
Compilation date and time, G-1l 
Compiler, 
version, G-l 
Compiler command line, 2-19, 
2-16 
Compiler error messages, H-l 
Compiler-generated PSECTs, D-1l, G-4 
Compiler limitations, C-l 
Compiler name, 2-9 
Compiler performance, 
Effect of qualification on, 7-12 


2-11, 2-16 


4-21 


2-11, 


Compiler switches, 2-11, 2-13, 2-14, 
2-15 
Compiler system errors, 12-1 
COMPUTATIONAL, 4-1, 4-2, 4-12 
COMPUTATIONAL-3, 4-5, 4-12 
COMPUTATIONAL-3 signs, 4-5 
COMPUTATIONAL-6, 4-3, 4-4, 4-12 
COMPUTE statement, 4-21, 14-19 
Concatenation of fields, 3-13 
Condition, 
AT END, 12-4 
Ciass, 3-6 
INVALID KEY, 6-35, 12-4 
Overflow, 3-17, 3-34 
Relation, 3-4 
Condition-names, 7-6 
Conventional format, 
identification field, G-2 
sequence number, G-2 
Conventional reference format, 2-1 


Conversion of reference format, 8-1 
COPY, 2-2, 2-3 
example, 2-4, 
use of, 2-4 
COPY in source listing, 2-8 
COPY REPLACING, 2-5, 2-6 
Count field, 6-4, 6-27 
COUNT phrase, 3-28 
Counter, 


Tally, 3-44 


2-5; .2-6y. 257 


/CREF switch, 2-13 
/CSEG:nnnn switch, 2-13, 9-2, 9-3 
/CVF switch, 2-13 


Data, 
Alphabetic, 3-1 
Alphanumeric, 3-1 
Non-numeric, 3-i 
Numeric, 3-1 

Data Division location, G~3 

Data item, 

Definition of, 7-19 
Qualification of, 7-19 

Data level buckets, 14-7 

Data map, G-3 

Data movement, 3-7 

Data-name subscripting, 5-11 

Data-names, 
maximum, C-1l 

Data organization, 

Data references, 
Qualified, 7-8 

DATE, 6-45 

Date, 
compilation, G-l 

DAY, 6-45 

Debugger, 


3-2 


2-195. 13-1 


Debugging session example, 13-11 


Decimal point, 
assumed, 4-6 
Decimal scaling position, 4-6 
DECLARATIVES, 6-49 
Defining a table, 5-1 
Defining data items, 7-19 
DELETE statement, 6-22, 6-35 
Deleting records from a relative 
file, 6-22 
Deleting records from an indexed 
file, 6-35 
DELIMITED BY phrase; 3-15, 
DELIMITER phrase, 3-29 
Delimiters, 
Multiple, 3-27 
Variable, 3-27 
DEPOSIT, 
CID command, 13-5, 13-6 
Determining buffer space, 6-8 
Device assignment, 6-43 
Device characteristics, 6-38 
Devices, 6-37 
Diagnostic, 
informational, 12-2, 12-3 
Diagnostic error messages, 12-1, H-1l 
Directory location, G-3 
Disk processing,. 6-38 
DISPLAY, 4-1 
Maximum number of operands, C-1 
DISPLAY statement, 6-39, 6-46 
DIVIDE statement, 4-21 
Dynamic access mode, 6-26, 6-32 
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Edited moves, 3-19 

elementary numeric, 4-13 
Efficient program structure, 14-2 
Elementary items, 3-2 
Elementary moves, 3-8 
Elementary numeric edited moves, 

4-13 

Elementary numeric moves, 4-11 
Embedded diagnostics, 12-1 
End-of-file mark, 6-3 
ENDS routine, E-3 
Environment, 

CID, 13-2 
/ERR switch, 2-13 
Error codes, 

sort, E-5 

terminal handling, F-5 
Error message summary, 2 
Error messages, 12-1 

diagnostic, H-l 

Merge utility, 2-23, 2-24, 2-25 

OTS, J-1 

RMS, I-1l 

Run-time, 12-5 
Error procedures, 

Run-time file I/O, 12-4 
7EX:n switch, 14-4, 14-12 
EXAMINE, 

CID command, 13-6 
Executing a COBOL task, 2-29, 2-39 
EXIT PROGRAM statement, 1f-3 
Explicit filenames, 6-41 
Expression processing, 

arithmetic, 4-22 
EXTEND mode, 6-11, 6-13 
Extend guantity, 14-4 


-15 


Fatal diagnostic, 12-3 
File, 6-49 
abbreviated ODL, 2-19 
listing, 1-1, 2-19 
merged ODL, 2-19 
Multi-volume, 6-3 
object, 1-2, 2-19 
ODL, 1-2, 2-16, 2-17 
Print, 6-13 
source, 2-19 
Storage, 6-13 
Transportable, 6-48 
File activity, 14-9 
File body, 
ODL, 11-2 
File design, 14-4 
File Handling, 6-1 
File header, 
ODL, 11-1 
File organization, 
indexed, 6-24 
relative, 6-13 
Sequential, 6-3 


File specification, 2-19, 6-49 
File specification switches, 14-11 
File status key values, 12-4 
File-to-LUN assignment table, G-2 
File types, 

COBOL, 6-2 
Filenames, 6-49 
Fixed-length records, 6-4, 6-14, 

6-27 

Form control characters, 6-47 
Formatting source programs, 7-1 


General formats, A-1 
GIVING phrase, 4-18 
GO, 
CID command, 13-7 
GO TO DEPENDING, C-l 
Good programming practices, 7-l 
Group items, 3-2 
Group moves, 3-8, 4-11 


/HELP switch, 2-13 
Hierarchy of index, 14-5 
HISEG, 2-26 


I/O buffer areas, 6-8, 6-18, 6-39 
I/O mode, 6-22 
I/O routines, 
overlaying, 2-19 
I/O statements, 6-2 
Identical tally arguments, 3-47 
Identification field, 
conventional format, G-2 
Identification number, 
compilation, 12-5, G-l 
IF statement, 3-4 
Illegal values in numeric fields, 
4-8 
Implicit redefinition of fields, 
3-38 
Including non-COBOL programs in 
task, 11-5 
Index buckets, 6-39 
Index data items, 5-14 
Index depth, 14-9 
Index structure, 14-5 
INDEXED BY phrase, 5-12, 5-17 
Indexed file organization, 6-24 
Indexed files, 14-5 
Sequential reading, 14-3 
Indexed I/O statements, 6-31 
Indexed OPEN modes, 6-32 
Indexed sending field, 3-14 
Indexed subscripting, 5-12 
Indexing, 5-9 
Relative, 5-13 


Informational diagnostic, 12-2, 12-3 


Initializing tables, 5-7 
Insertion, 
Blank, 3-19 
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Insertion (continued) 
Slash, 3-19 
zero, 3-19 
INSPECT operation, 3-49 
INSPECT statement, 3-36 
Inter-program communications, 19-1 
Interactive debugger, 13-1 
Interference of replacement 
arguments, 3-54 
Interference of tally arguments, 
3-47 
Intermediate results, 4-15, 4-25 
INVALID KEY clause, 6-19, 6-35 
INVALID KEY condition, 12-4 


JUSTIFIED clause, 3-9 
Justified moves, 3-19 


KBASGN terminal handling routine, 
F-2, F-3 
KBCLOS terminal handling routine, 
F-2 
KBDEAS terminal handling routine, 
F-3 
KBOPEN terminal handling routine, 
F-2 
KBREAD terminal handling routine, 
F-4 
KBREAU terminal handling routine, 
F-4 
KBWRIT terminal handling routine, 
F-3 
/KER:kk switch, 2-14 
Key, 
Definition of, 6-24 
Key value, 14-7 
Keys, 
sort, E-3 


LEADING condition, 3-49 
Legal non-numeric elementary moves, 
3-9 
Level 88, 7-6 
Level number, 7-19 
Library facility, 2-2 
common errors, 2-8 
Library file, 
creating, 2-3 
Library text, 
merging, 2-4 
Limitations, 
compiler, C-l 
LINAGE clause, 6-6 
LINAGE counters, 6-11 
Line number, 
source, G-l 
Line printer, 6-39 
LINKAGE SECTION, 19-2 
Linking sort routines, E-4 


Listing, 
source, G-l 

Listing file, 1-1, 2-19 

Literal sending field, 3-14 

Literal subscripting, 5-9 

/LO switch, 14-12 

Location, 
Data Divi 


iLViSion G-3 


sig ¥ 
directory, G-3 
LOCK option, 6-24, 6-37 
Logical block, 6-6, 6-15, 6-27 
Logical block size, 6-6 
Logical name assignment, 6-39 
Logical processing units, 
Grouping of, 7-4 
Logical Unit Number, 6-43 
Logical unit number assignment, B-1 
LUN, E-4 
relative, G-2 
LUN assignment, 6-43, B-1l 


MACRO programs, 
Calling, 19-4 
Magnetic tape processing, 6-39 
Main program, 
COBOL, 19-1 
Map, 
data, G-3 
procedure name, G-3 
/MAP switch, 2-14, 13-1, G-3 
Mapping table elements, 5-3 
Mass storage I/O, 
Optimizing, 14-1 
Merge, 1-3, 2-16, 2-17, 2-18 
ODL files for, 1l-l 
Merge dialogue, 2-19, 2-29, 2-21 
example, 2-22, 2-23 
MERGE routine, E-2 
Merge utility, 2-16 
Merge utility error messages, 2-23, 
2-24, 2-25 
Merged ODL file, 2-19 
Merging library text, 2-4 
Merging ODL files, 11-5 | 
Mode, 
EXTEND, 6-13 
OUTPUT, 6-12 
Modifying ODL files, 11-6 
Modular programs, 1-2 
Module, 
object code, 1-1 
MOVE CORRESPONDING, 3-8, 3-12 
MOVE statement, 3-7, 3-8, 4-12 
numeric, 4-19 
Moves, 
elementary numeric, 4-11 
elementary numeric edited, 4-13 
group, 4-11 
Multi-block read and write, 14-3 
MULTI-FILE TAPE clause, 6-39 
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Multi-volume files, 6-3 

Multiple delimiters, 3-27 

Multiple operands, 4-18 

Multiple receiving fields, 3-1l, 
3~21 

Multiple sending fields, 3-13 

MULTIPLY statement, 4-29 


Names, 

PSECT, D-1l 
Nested PERFORM source line number, 

12-5 

Nesting of parentheses, C-1l 
Nesting of PERFORM statements, C-1l 
/NL switch, 2-14 
NO ADVANCING phrase, 6-47 
Non-COBOL object modules, 19-4, 11-5 
Non-edited moves, 3-11 
NOT, 3-5 


Numeric character handling, 4-1 
Numeric data, 3-1 
Numeric edited moves, 
elementary, 4-13 
Numeric fields, 
-illegal values, 4-8 
testing, 4-8 
Numeric MOVE statement, 4-19 
Numeric moves, 
common errors, 4-14 
elementary, 4-11 
/OBJ switch, 2-14, 13-1, G-2 


Object code module, 1-1 
Object file, 1-2, 2-19 
Object file input to Task Builder, 
2-27 
Object modules, 1-1 
Non-COBOL, 1f-4 
Object-time system, 1-3 
Object-time system error messages, 
J-1 
OCCURS clause, 5-l, 5-2, 5-17 
ODL directives for overlays, 11-3 
ODL file, 1-1, 1-2, 2-16, 2-17 
abbreviated, 2-19 
merged, 2-19 
on source listing, G-5 
Rearranging, 11-6 
Standard, 11-1 
ODL file body, 11-2 
ODL file header, 11-1 
ODL file input to Task Builder, 2-25 
ODL file merging, 11-5 
ODL files for Merge, 11-1 
ODL files for Task Builder, 11-1 
Offset, 12-5, 13-3, 13-4 
OPEN I-O statement, 14-3 
OPEN statement, 6-9, 6-29, 
Opening indexed files, 6-33 
Opening relative files, 6-29 


6-33 


Opening sequential files, 6-9 
Operating system prompts, 2-9 
Operator, 

Relational, 3-5 
Optimization, 14-1 
Optimizing computation, 14-19 
Options, 


Task Builder, 2-26 
ORGANIZATION clause, 6-1 
OTS, 1-3 
OTS action on OPEN, 6-19 


OTS error checking, 19-3 
OTS error messages, J-l 
OTS operations on subscripted 
references, 5-11 
OTS routines, 
on source listing, G-4 
OUTPUT mode, 6-12, 6-22 
/OV switch, 9-2 
Overflow condition, 3-17, 3-34 
OVERFLOW phrase, 3-17, 3-33 
Overhead accumulation, 14-9 


Overlay Description Language, 1-1 


Overlay structure, 14-2 
Overlaying I/O routines, 2-19 


Parentheses, 
nesting of, C-1l 
Passing of arguments, 19-3 
PERFORM statement, 7-5 
PERFORM statement nesting, C-1l 
7PFM:nn switch, 2-14, C-l 
/-PLT switch, 2-14 
Pointer, 
Bucket, 14-7 
POINTER phrase, 
Position, 
decimal scaling, 4-6 
Preallocation of file, 14-4 
Primary key, 6-24 
Primary key index, 14-7 
Print-controlled records, 
Print files, 6-13 
Procedure name map, G-3 
Procedure-names, 
maximum, C-1l 
Procedure reference, 
Qualified, 7-11 
Processing I/O errors, 6-49 
Program development, 14-2 
PROGRAM-ID, 1-3, 12-5 
Program initiation in CID, 
Program segments, 
Non-overlayable, 9-1 
Overlayable, 9-1 
Program suspension in CID, 13-9 
Program switches, 2-29, 2-39 


3-14, 3-36, 


6-6 


13-8 


Program termination in CID,. 13-9 


Prompts, 


operating system, 2-9 
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PSECT, 9-2, 12-5 
compiler-generated, D-1l, G-4 
on source listing, G-4 

PSECT names, 19-3, D-1 

PSECT size, G-4 

Punctuation, 

Use of, 7-4 


Qualification and performance, 7-12 
Qualified procedure reference, 7-11 
Qualified references, 7-8 
Qualifiers, 

maximum number, C-]l 
Qualifying data items, 7-19 


RANDOM access mode, 6-19 
Random access mode, 6-32 
READ NEXT statement, 6-21, 6-23 
READ statement, 6-11, 6-21, 6-34 
Reading buckets, 6-17 
Reading indexed files, 6-34 
Reading relative files, 6-21 
Reading sequential files, 6-11 
Rearranging ODL files, 11-6 
Receiving fields, 
Multiple, 3-21 
Record, 
Fixed-length, 6-4 
fixed-length, 6-14 
variable-length, 6-14 
Record blocking, 6-6, 6-15, 6-27 
RECORD CONTAINS clause, 6-4, 6-14, 
6-27 
Record Management Services, 6-47 
Record size, 6-4, 6-14, 6-27 
Redefinition, 
implicit, 3-38 
Reference format, 2-1 
conventional, 2-1 
terminal, 2-1 
Reference format conversion, 8-1 
REFORMAT command string, 8-2 
REFORMAT error messages, 8-3 
REFORMAT utility program, 7-1, 8-1 
Relation condition, 3-4 
Relation tests, 3-4, 4-8 
Relative file organization, 6-13 
Relative files, 14-5 
Relative I/O statements, 6-18 
Relative indexing, 5-13 
RELATIVE KEY clause, 6-23 
Relative LUN, G-2 
RELES routine, E-2 
Replacement argument, 3-52 
Replacement argument list, 3-53 
Replacement arguments, 
Interference of, 3-54 
Replacement value, 3-52 
REPLACING, 2-5, 2-6 
REPLACING arguments, 3-49 


REPLACING phrase, 3-36, 3-51 
RESERVE clause, 6-8, 6-18, 6-39 
Results, 

intermediate, 4-15, 4-25 
RETRN routine, E-2 
Returning from a subprogram, 1f-3 
REWRITE statement, 6-12, 6-22, 6-34 
Rewriting records, 

indexed file, 6-34 

relative file, 6-22 

sequential files, 6-12 
RMS default overlay structure, 14-2 
RMS DEFINE utility, 14-4, 14-5 
RMS error codes, I-l 
RMS error messages, I-l 
/RO switch, 2-15 
Root bucket, 14-5 
ROUNDED phrase, 4-16 
RSORT routine, E-l 
RSTS/E terminal handling, F-l 
RUN command, 2-39 
Run-time error messages, 12-5 
Run-time I/O errors, 12-4 
Run-time system, 1-3 


SAME AREA clause, 6-8, 6-13, 6-18, 
6-24, 6-31, 6-37, 14-4 
SAME RECORD AREA clause, 6-5, 6-15, 
6-27, 14-4 
Scanner, 
INSPECT, 3-41 
Search argument, 
REPLACING, 3-51 
SEARCH statement, 5-16 
SEARCH verb, 5-16 
Section, 
Linkage, 1f-2 
Section-name, 9-1 
SEGMENT-LIMIT clause, 9-1 
Segment-number, 9-1 
Segmentation, 9-1 
SELECT statement, 7-1 
Selecting bucket size, 14-8 
Sequence number, 
conventional format, G-2 
Sequential access mode, 6-19, 6-32 
Sequential file organization, 6-3 
Sequential files, 14-4 
Sequential I/O statements, 6-9 
SEQUENTIAL organization, 14-3 
Sequential reading of indexed files, 
14-3 
Sequential search of table, 5-16 
SET BREAKPOINT, 
CID command, 13-7 
SET statement, 5-12, 5-14 
Setting the INSPECT scanner, 3-41 
Severity code, G~2 
Severity level of diagnostic, 12-3 
/SH switch, 14-12 
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Sharing buffer space among files, 
6-8, 6-18, 6-31 
SHOW BREAKPOINTS, 
CID command, 13-8 
Sign conventions, 4-6, 4-7 
Sign movement, 4-12 
Sign tests, 4-9 
Signs, 
COMPUTATIONAL-3, 4-5 
SIZE ERROR phrase, 4-17 
Slash insertion, 3-19 
Sort error codes, E-5 
Sort keys, E-3 
Sort routine, 
ENDS, E-3 
MERGE, E-2 
RELES, E-2 
RETRN, E- 
RSORT, E-1l 
Sort routines, 
linking, E-~-4 
Sorting, E-1 
Source file, 2-19 
Source line number, G-l 
Source program, 
creating, 2-1 
entering, 2-2 
Source program formatting, 7-1 
Source program listing, G-l 
Special characters, 3-3 
SPECIAL-NAMES, 2-29, 2-38, 6-39 
Specifying bucket size, 6-28 
Specifying next record to be read, 
6-23, 6-35 
Specifying Task Builder options, 
11-8 
Standard ODL file, 11-1 
START statement, 6-23, 6-35 
Statement, 
DISPLAY, 6-39 
STRING, 3-7 
Statements, 
arithmetic, 4-15 
Storage files, 6-13 
STRING statement, 3-7, 3-18 
Structure of index, 14-5 
Subordinate data items, 3-2 
Subprogram, 
COBOL, 19-1 
Return from, 19-3 
Subprogram arguments, 19-3 
Subprogram calls, 1f-2 
Subprogram references, G-5 
Subscript evaluation, 
Sequence of, 3-35 
Subscripted fields in INSPECT 
statement, 3-43. 
Subscripted fields in STRING 
statement, 3-18 


Subscripted fields in UNSTRING 

statement, 3-34 
Subscripted moves, 3-1l 
Subscripting, 3-19, 5-9 
Subscripting operations by software, 

5-19 

Subscripting with data-names, 5-1l 
Subscripting with indexes, 5-12 
Subscripting with literals, 5-9 
SUBTRACT statement, 4-19 

multiple operands, 4-18 
Switch, 

/ACC:n, 2-12, 2-15, 12-4 

/AL:n, 14-4, 14-11 

/-BOU, 2-12, 14-19 

/CL:in, 14-11 


/CM6, 2-13 
/COsn;, 14-4, 14-12 
/CREF, 2-13 


/CSEG:nnnn, 2-13, 9-2, 9-3 

/CVF, 2-13 

/ERR, 2-13 

/EX:n, 14-4, 14-12 

/HELP, 2-13 

/KER:kk, 2-14 

/LO, 14-12 

/MAP, 2-14, 13-1, G-3 

/NL, 2-14 

/OBJ, 2-14, 13-1, G-2 

/OV, 9-2 

/PFM:nn, 2-14, C-1l 

/~PLT, 2-14 

/RO, 2-15 

/SH, 14-12 

/SYM:n, 2-15 

/Wi:n, 14-12 
Switches, 

compiler, 2-11, 2-13, 2-14, 2-15 

File specification, 14-11 

program, 2-29, 2-39 
/SYM:n switch, 2-15 
SYNCHRONIZED clause, 5-3 


Table, 
Definition of, 5-1 
variable-length, 5-2 
Table Handling, 5-1 
Table search, 
Binary, 5-17 
Sequential, 5-16 
Tally argument, 3-44 
Interference of, 3-47 
Tally arguments, 
identical, 3-47 
Tally counter, 3-44 
TALLYING arguments, 3-49 
TALLYING phrase, 3-31, 3-32, 3-36, 
3-43 
Target bucket, 14-7 
Task, 1-3 
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ODL file input, 2-25 
ODL files for, 11-1 
Task Builder options, 2-26, 11-8 
Task-building, 2-25 
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Terminal handling error codes, F-5 
Terminal handling routine, 


KBASGN, 
KBCLOS, 
KBDEAS, 
KBOPEN, 
KBREAD, 
KBREAU, 
KBWRIT, 


F-2, F-3 
F-2 
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Terminal reference format, 2-1, 


Testing non-numeric fields, 3-4 


Testing numeric fields, 4-8 


Tests, 
class, 3 
relation 
sign, 4- 

TIME, 6-45 


Time of compilation, G-1l 


Truncation 


v 4-8 
9 


7 4-1l, 


4-12 
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Unique reference, 7-11 
UNSTRING statement, 3-7, 3-21 
Usage, 

On source listing, G-3 
Usages, 4-1 
USE procedure, 12-4 
USE statement, 6-49 
USING phrase, 1f-1 
Utility programs, 1-3 


Value, 

Replacement, 3-52 
VALUE clause, 5-1 
VALUE OF ID clause, 6-49, 6-41 
Variable delimiters, 3-27 
Variable-length records, 6-14, 6-27 
Variable-length tables, 5-2 
Version of compiler, G-l 
Virtual block, 6-6, 6-15, 6-27 


Warning diagnostic, 12-3 
/WI:n switch, 14-12 
WRITE statement, 6-6, 6-12, 6-22 


XIT, 
CID command, 13-8 


zero insertion, 3-19 
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